AI Video

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

Beta. These endpoints are in beta and may change. Available to any account with an active paid subscription — no separate allowlisting.

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.

Native audio is on by default at no extra cost everywhere — the price depends only on model, resolution, and duration. Prompt length is 5000 characters on Seedance, 2500 on Kling, 20000 on Wan. These are hard caps, not targets: for Seedance, BytePlus recommends keeping each prompt to about 500 Chinese characters or 1,000 English words — longer prompts are accepted, but the model tends to pick out the main points and drop details. Seedance models accept aspect ratios 16:9 / 9:16 / 4:3 / 3:4 / 1:1. Kling and Wan differ in several ways — read the values from the models endpoint rather than assuming Seedance behaviour:

• kling-3.0 accepts no refs; kling-3.0-omni accepts up to 7 image/video references (no audio) at no extra cost. With a video reference Kling cannot produce native audio, so generate_audio=true together with a video ref is rejected with 400 — leave it off when attaching video.
• Kling aspect ratios are 16:9 / 9:16 / 1:1; for image-to-video the aspect ratio follows first_frame and an explicit aspect_ratio is rejected with 400.
• Kling moderates the prompt and image inputs synchronously at submit (HTTP 403 with 37110 / 37111, nothing charged); Seedance moderates asynchronously (see Content moderation below).
• 480p is available on every Seedance and Wan model and is the cheapest tier — seedance-2.0-fast and seedance-2.0-mini at 480p are 1 credit/s. Kling has no 480p tier. 4K is available on kling-3.0 only, at 8 credits/s — quote it first.
• kling-3.0-omni is the only model that defaults to 1080p; every other model defaults to 720p. Opening the cheaper 480p tier did not change any model's default, so it costs nothing to ignore.
• Omitting resolution on kling-3.0-omni therefore costs 3 credits/s — pass resolution explicitly, or quote with GET /api/v1/ai_video/cost first.
• Wan accepts image, video and audio references, and is the only model that takes any integer duration from 2 to 30 s. Per-type reference limits are 10 image / 5 video / 5 audio, with video and audio each capped at 15 s of material in total; the models endpoint returns these as refs.max_per_kind and refs.total_duration_sec_max. refs.max (20) is the combined count across all three types, not a per-type limit.
• Wan follows the reference material for framing whenever refs is set, so passing aspect_ratio together with refs is rejected with 400. Its default aspect_ratio is adaptive, which also follows the input material; for image-to-video the framing always follows first_frame.
• Wan reference video and audio longer than 15 s is truncated to the first 15 s rather than rejected.
• Wan moderates synchronously at submit, like Kling.
• The API never substitutes another model: if the model you chose fails, the task resolves to failed and credits are refunded in full. model_id on the task is always the model that rendered it.

Credits and cost

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

# seedance-2.0, 8 s at 1080p: 8 x 8 = 64 credits
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
  }
}

# kling-3.0, 10 s at 4K: 8 x 10 = 80 credits
curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/ai_video/cost?model_id=kling-3.0&duration_sec=10&resolution=4k"

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:

Limits differ per model — the exact values for each slot are returned in first_frame and refs.image / refs.video / refs.audio of GET /api/v1/ai_video/models. Summary:

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 timing depends on the model. Seedance 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. Kling and Wan models (kling-3.0, kling-3.0-omni, wan-3.0, wan-3.0-prime) check the prompt and any image inputs (first_frame, end_frame, image refs) synchronously at submit and reject with HTTP 403 37110 (prompt) / 37111 (image) before any credits are charged. 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). status filters by task status — comma-separated, any of queued, creating, created, failed. DELETE /api/v1/ai_video?video_id= deletes a task — only your own.

status=queued,creating returns exactly the tasks that occupy your per-key concurrency quota, so len(videos) is how many slots you are using. Call it before a burst of submissions to stay under the limit instead of discovering it through 429s:

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" "https://openapi.visionstory.ai/api/v1/ai_videos?status=queued,creating&limit=100" | jq '.data.videos | length'

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 (Seedance 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. The 429 body carries the numbers in error.details: {"limit": N, "in_flight": M} — read limit from there once and self-throttle, or poll GET /api/v1/ai_videos?status=queued,creating before submitting.
• 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.
• Developer tools — SDK, CLI, MCP, and Agent Skill documentation.
• API reference — full schemas for every endpoint above.