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 allowlisted API keys. Per-key concurrency is limited during beta; submissions beyond the limit are rejected rather than queued.
Headers
X-API-KeystringrequiredYour VisionStory API key (sk-vs-...), kept server-side. Create or manage keys in API keys (Pro plan and up).
Request body
application/jsonrequiredaspect_ratiostring | nullnullableControls the output frame shape. Text-to-video defaults to 9:16 for 2.5 / 2.0 / fast and 16:9 for mini. Image-to-video defaults to 16:9 for every model.
client_request_idstring | nullnullableOptional 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 | nullnullableseedance-2.5: any whole second from 4–30 (default 15). All seedance-2.0 variants: any whole second from 4–15 (default 5). Longer clips cost more credits.
end_frameMediaRef | nullnullableOptional last-frame image with the same limits as first_frame. Requires first_frame.
asset_idstring | nullnullableAsset ID from POST /api/v1/asset; use for materials reused across requests.
inline_dataInlineDataModel | nullnullableInline base64 media data for one-off use; not added to your asset library.
datastringrequiredThe file's raw bytes encoded as a base64 string (no data: URI prefix).
mime_typestringrequiredMIME 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'].
urlstring | nullnullablePublicly accessible media URL for one-off use; not added to your asset library.
first_frameMediaRef | nullnullableFirst-frame image for image-to-video. Accepts JPEG, PNG, WebP, BMP, TIFF, or GIF up to 30 MB, 300–6000 px per side, and aspect ratio 1:2.5–2.5:1. Mutually exclusive with refs.
asset_idstring | nullnullableAsset ID from POST /api/v1/asset; use for materials reused across requests.
inline_dataInlineDataModel | nullnullableInline base64 media data for one-off use; not added to your asset library.
datastringrequiredThe file's raw bytes encoded as a base64 string (no data: URI prefix).
mime_typestringrequiredMIME 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'].
urlstring | nullnullablePublicly accessible media URL for one-off use; not added to your asset library.
generate_audioboolean | nullnullableControls whether the generated video includes a native audio track.
model_idstringrequiredChoose the generation model. The values below are the currently supported IDs; query GET /api/v1/ai_video/models for the latest availability.
promptstringrequiredDescribe the video or, when first_frame is present, the motion to apply. Length: 1–2500 characters.
refsMediaRef[] | nullnullableUp to 9 reference images, videos, or audio files for text-to-video. Image: ≤30 MB. Video: MP4/MOV, ≤100 MB, 2–15 s, 24–60 fps. Audio: WAV/MP3, ≤15 MB, 2–15 s and cannot be the only reference. Mutually exclusive with first_frame.
asset_idstring | nullnullableAsset ID from POST /api/v1/asset; use for materials reused across requests.
inline_dataInlineDataModel | nullnullableInline base64 media data for one-off use; not added to your asset library.
datastringrequiredThe file's raw bytes encoded as a base64 string (no data: URI prefix).
mime_typestringrequiredMIME 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'].
urlstring | nullnullablePublicly accessible media URL for one-off use; not added to your asset library.
resolutionstring | nullnullable1080p is available only on seedance-2.0. Higher resolution costs more credits.
Responses
200Successful Response
application/json
dataCreateAiVideoResponse | nullrequirednullableThe 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.
cost_creditintegerCredits charged for this task on submission; auto-refunded if generation fails.
statusstringInitial task status; always queued right after creation.
video_idstringrequiredIdentifier of the created task. Poll GET /api/v1/ai_video with it to track progress.
messagestringHuman-readable status message; "success" on a successful call.
server_timestring · date-timerequiredServer-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
errorErrorDetailrequiredcodeintegerrequiredMachine-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 | nullnullableOptional 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 | nullnullableActionable 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.
messagestringrequiredHuman-readable explanation of what went wrong. Safe to log or surface to end users; not localized.