AI Video

Generate AI videos with Seedance models — text-to-video, image-to-video, and multimodal references — through the same API key and billing you already use for talking avatars.

Beta access. These endpoints are available to allowlisted accounts only. If a request returns 403 / access not enabled, contact your VisionStory representative to enable your account. An active subscription is required.

Endpoints

Quick start

Submit a text-to-video task, then poll until it finishes:

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"model_id": "seedance-2.0", "prompt": "A corgi surfing at sunset, cinematic lighting", "duration_sec": 8, "aspect_ratio": "9:16", "resolution": "1080p"}' https://openapi.visionstory.ai/api/v1/ai_video

{ "data": { "video_id": "7241059991822401536", "status": "queued", "cost_credit": 64 } }

Poll every 5–10 seconds:

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/ai_video?video_id=7241059991822401536"

Models

GET /api/v1/ai_video/models returns allowed values and defaults for each parameter, plus media constraints. Always drive your integration from this endpoint — new models and parameter values appear there without any API change.

Common to all current models: aspect ratios 16:9 / 9:16 / 4:3 / 3:4 / 1:1, prompt up to 2500 characters, native audio generation on by default (generate_audio).

Credits and cost

Generation is billed in credits, charged at submit time and automatically refunded in full if generation fails. Cost depends on model, resolution, and duration (per second). Query the cost endpoint before submitting — it applies exactly the same formula as billing:

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/ai_video/cost?model_id=seedance-2.0&duration_sec=8&resolution=1080p"

{ "data": { "credit": 64 } }

Check your remaining balance with GET /api/v1/billing/credits.

Media inputs

Every media slot (first_frame, end_frame, refs[]) accepts exactly one of three forms:

Create a video

POST /api/v1/ai_video has two modes on one endpoint: provide first_frame (optionally end_frame) for image-to-video, provide refs for reference-guided text-to-video (character consistency, style, motion, or voice references), or provide neither for pure text-to-video. refs and first_frame are mutually exclusive. Unknown fields and unsupported values are rejected — nothing is silently ignored.

Image-to-video with first and last frame:

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"model_id": "seedance-2.0", "prompt": "The scene slowly comes alive, gentle camera push-in", "first_frame": {"url": "https://your.site/start.jpg"}, "end_frame": {"url": "https://your.site/end.jpg"}, "duration_sec": 6}' https://openapi.visionstory.ai/api/v1/ai_video

Character-consistent generation with a reusable asset:

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"model_id": "seedance-2.0", "prompt": "The same woman walks through a neon-lit street at night", "refs": [{"asset_id": "7241058823145623552"}], "duration_sec": 10}' https://openapi.visionstory.ai/api/v1/ai_video

Query and poll

Query one task with ?video_id=, or up to 20 at once with ?video_ids=id1,id2,... (batch responses return {"videos": [...]}). Poll every 5–10 seconds.

Content moderation is asynchronous. A submission that violates content policy is accepted at submit time and later resolves to failed with an explanatory error — always handle the failed state. Failed tasks never consume credits.

List and delete

GET /api/v1/ai_videos lists your tasks, newest first. Pass cursor from the previous page's next_cursor to paginate; next_cursor=0 means no more pages. limit defaults to 20 (max 100). DELETE /api/v1/ai_video?video_id= deletes a task — only your own.

Assets

An asset is a reusable uploaded material: upload once, reference by asset_id in any number of generation requests — ideal for a recurring character image, brand footage, or a voice sample. Re-uploading identical content returns the existing asset (idempotent):

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"url": "https://your.site/character.jpg"}' https://openapi.visionstory.ai/api/v1/asset

{ "data": { "asset_id": "7241058823145623552", "kind": "image", "mime": "image/jpeg", "width": 1024, "height": 1536, "duration_sec": 0, "created_at": 1754270000 } }

inline_data (base64) is also accepted; size and format limits match Media inputs above. GET /api/v1/assets lists your assets (filter by kind, paginate with cursor / limit). DELETE /api/v1/asset?asset_id= deletes an asset — videos already generated from it are not affected.

Errors

Asynchronous failures (moderation, provider errors) never use HTTP errors — the task resolves to status=failed with an error object, and credits are refunded automatically.

Limits and notes

• Concurrency: per-key concurrency is limited during beta; requests beyond the limit are rejected, not queued.
• Rate limit: 180 requests per 60 seconds per account. Use batch query (video_ids) and poll at 5–10 s intervals.
• Storage: download video_url promptly if you need long-term storage. Assets stay available until you delete them.
• Idempotency: pass a client_request_id on submit to make retries safe — resubmitting the same value within 24h returns the original task instead of creating (and charging) a new one. Without it, store the returned video_id before retrying, since a network-level retry of a successful submit creates (and charges) a new task.
• Webhooks are not available yet; polling is the supported integration pattern.
• The beta surface may gain new optional parameters and models over time; existing fields and semantics will not change incompatibly.

Next steps

• Quick start — the talking-avatar flow with the same key.
• For agents — drive AI video generation from an AI agent.
• API reference — full schemas for every endpoint above.