Generate video — VisionStory API

Generate a talking-avatar video: an avatar speaks a script provided either as text-to-speech (text_script) or pre-recorded audio (audio_script). Generation is asynchronous — poll GET /api/v1/video for status. Finished videos are retained for 7 days, so download promptly.

Pass client_request_id to make retries idempotent (no double charge).

Headers

X-API-Keystringrequired

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

Request body

application/jsonrequired

aspect_ratiostring

Output aspect ratio for the rendered video; defaults to 9:16.

Values: 9:1616:91:1

Default: 9:16

audio_scriptAudioScript | nullnullable

Pre-recorded narration audio to drive the avatar. Provide either audio_script or text_script.

audio_urlstring | nullnullable

Publicly reachable URL of narration audio to drive the avatar. Provide either this or inline_data.

denoiseboolean

If true, apply noise reduction to the uploaded audio before generation.

Default: false

inline_dataInlineDataModel | nullnullable

Narration audio as inline base64 data. Provide either this or audio_url.

datastringrequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

mime_typestringrequired

MIME type of the inline data, used to detect image vs audio. Audio: ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav']; images: ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].

voice_changeboolean

If true, re-synthesize the uploaded audio with the voice in voice_id (voice conversion) while keeping the original timing.

Default: false

voice_idstring | nullnullable

Target voice for conversion when voice_change is true. Use an id from GET /api/v1/voices.

avatar_idstringrequired

Avatar that speaks the script. Use an id from GET /api/v1/avatars (public or your own).

background_colorstring

Optional solid background as a 6-digit hex color, e.g. #00b140. Leave empty to keep the avatar's original background; setting it renders the avatar on this color (chroma-key friendly).

Default:

client_request_idstring | nullnullable

Optional idempotency key. Resubmitting with the same value within 24h returns the original task instead of creating (and charging) a new one. Safe for retries.

emotionstring

Expressive tone the avatar performs; defaults to cheerful.

Values: cheerfulangrymarketingnewssinging

Default: cheerful

model_idstring

Rendering model to use; see GET /api/v1/models. Defaults to vs_character_v4. Note: when omitted and resolution is 480p, vs_talk_v1 is selected automatically.

Values: vs_character_v4vs_talk_v1

Default: vs_character_v4

resolutionstring

Output resolution. Higher values cost more credits and take longer to render; defaults to 720p. Note: vs_talk_v1 does not support 2k.

Values: 480p720p1080p2k

Default: 720p

text_scriptTextScript | nullnullable

Text-to-speech script (text + voice). Provide either text_script or audio_script.

speech_ratestring | nullnullable

Speaking speed of the synthesized voice; defaults to normal.

Values: slownormalfast

Default: normal

textstringrequired

The script to speak; converted to speech with the selected voice.

voice_idstringrequired

Voice to synthesize the script with. Use an id from GET /api/v1/voices (a public or your own cloned voice).

Responses

200Successful Response

application/json

dataCreateVideoResponse | nullrequirednullable

The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete.

video_idstringrequired

Identifier of the newly created video task. Poll GET /api/v1/video with it to track progress.

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.