Delete avatar — VisionStory API

Delete one of your custom avatars by avatar_id. Only avatars you created can be deleted; public avatars are unaffected.

Agent safety: require an explicit user request and confirmation immediately before calling this destructive operation.

Headers

X-API-Keystringrequired

Your VisionStory API key (sk-vs-...), kept server-side. Create or manage keys in API keys (Pro plan and up).

Query parameters

avatar_idstringrequired

Id of the custom avatar to delete, as returned by POST /api/v1/avatar (the avatar_id field). Only avatars you created can be deleted; public avatars are unaffected.

Responses

200Successful Response

application/json

dataDeleteResponse | nullrequirednullable

Common response body for DELETE endpoints (avatar / voice / video / ai_video / asset).

deletedboolean

Always true when the request succeeded — the resource has been removed and no longer appears in list endpoints. Deletes are idempotent: deleting an already-removed resource still returns true.

Default: true

messagestring

Human-readable status message; "success" on a successful call.

Default: success

server_timestring · date-timerequired

Server-side timestamp when the response was produced, in ISO 8601 format (UTC).

defaultError response. All failures share one envelope: an error object with a numeric code, a human-readable message, an optional details string, and an optional hint giving an actionable next step (useful for AI agents).

application/json

errorErrorDetailrequired

codeintegerrequired

Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.

detailsstring | nullnullable

Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.

hintstring | nullnullable

Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.

messagestringrequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.