Generate AI video — VisionStory API

Generate a video with a frontier AI model. Provide first_frame (optionally end_frame) for image-to-video, refs for multimodal text-to-video, or neither for pure text-to-video. Credits are charged on submission and refunded automatically if generation fails; poll GET /api/v1/ai_video for progress.

Beta: available to any account with an active paid subscription. Per-key concurrency is limited during beta; submissions beyond the limit are rejected rather than queued.

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 | nullnullable

Aspect ratio such as 16:9 / 9:16 / 1:1, or adaptive to let the model follow the input material. Allowed values vary by model; defaults to the model default. wan-3.0 always follows the references when refs is set, so passing both is a 400.

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.

duration_secinteger | nullnullable

Clip length in seconds. Allowed values vary by model (see GET /api/v1/ai_video/models); defaults to the model default. Longer clips cost more credits.

end_frameMediaRef | nullnullable

A media reference — provide exactly one of: asset_id (from the asset library, reusable across requests), url (one-off public URL), or inline_data (one-off base64, not stored).

asset_idstring | nullnullable

Asset ID from POST /api/v1/asset; use for materials reused across requests.

inline_dataInlineDataModel | nullnullable

Inline base64 media data for one-off use; not added to your asset library. Images: image/jpeg, image/jpg, image/png, image/webp, image/bmp, image/tiff, image/gif; audio: audio/wav, audio/x-wav, audio/wave, audio/mpeg, audio/mp3; video: video/mp4, video/quicktime, video/mov.

datastringrequired

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

mime_typestringrequired

MIME type of the inline data; the gateway uses it to tell image / audio / video apart. The accepted set depends on the endpoint — see the field carrying this object. Talking video accepts audio ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav'] and images ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].

urlstring | nullnullable

Publicly accessible media URL for one-off use; not added to your asset library.

first_frameMediaRef | nullnullable

A media reference — provide exactly one of: asset_id (from the asset library, reusable across requests), url (one-off public URL), or inline_data (one-off base64, not stored).

asset_idstring | nullnullable

Asset ID from POST /api/v1/asset; use for materials reused across requests.

inline_dataInlineDataModel | nullnullable

datastringrequired

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

mime_typestringrequired

urlstring | nullnullable

Publicly accessible media URL for one-off use; not added to your asset library.

generate_audioboolean | nullnullable

Whether to generate a native audio track; defaults to true on every model and never changes the price. kling-3.0-omni cannot combine it with a video reference (400).

model_idstringrequired

Model to generate with. Use an id from GET /api/v1/ai_video/models, e.g. seedance-2.0.

promptstringrequired

Text description of the video to generate. For image-to-video it describes the motion applied to first_frame.

refsMediaRef[] | nullnullable

Multimodal reference materials (image/video/audio) that guide text-to-video. Only models whose refs.max is greater than 0 in GET /api/v1/ai_video/models accept it; refs.max_per_kind and refs.total_duration_sec_max there give the per-type limits. References never change the price. Mutually exclusive with first_frame.

asset_idstring | nullnullable

Asset ID from POST /api/v1/asset; use for materials reused across requests.

inline_dataInlineDataModel | nullnullable

datastringrequired

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

mime_typestringrequired

urlstring | nullnullable

Publicly accessible media URL for one-off use; not added to your asset library.

resolutionstring | nullnullable

Output resolution such as 480p / 720p / 1080p / 4k. Allowed values vary by model (4K is kling-3.0 only; 480p is available on every Seedance and Wan model but not on Kling); defaults to the model default — kling-3.0-omni is the only model that defaults to 1080p, every other model defaults to 720p. Higher resolutions cost more credits.

Responses

200Successful Response

application/json

dataCreateAiVideoResponse | nullrequirednullable

The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.

cost_creditinteger

Credits charged for this task on submission; auto-refunded if generation fails.

Default: 0

statusstring

Initial task status; always queued right after creation.

Default: queued

video_idstringrequired

Identifier of the created task. Poll GET /api/v1/ai_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.