AI Video Generation API

The VisionStory AI Video Generation API creates text-to-video, image-to-video, and reference-guided clips with Seedance, Wan, and Kling models. Use the same API key to discover models, estimate credits, submit jobs, reuse media assets, poll status, and download results.

Beta. Any API key backed by an active Pro plan or above can call these endpoints. No separate capability allowlist is required.

AI video API endpoints

Generate an AI video

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": "YOUR_AI_VIDEO_ID",
    "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=YOUR_AI_VIDEO_ID"

AI video models and capabilities

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.

| wan-3.0 | Multimodal references | 480p / 720p / 1080p | 2–30 s, integer | text-to-video, image-to-video | | wan-3.0-prime | Higher-priced Wan variant | 480p / 720p / 1080p | 2–30 s, integer | text-to-video, image-to-video | | kling-3.0 | Up to 4K output | 720p / 1080p / 4k | 5 or 10 s | text-to-video, image-to-video; no refs | | kling-3.0-omni | Image/video references | 720p / 1080p | 3, 5, 7, 10, or 15 s | text-to-video with refs; no first_frame |

Read each model's allowed aspect ratios, defaults, and reference limits from discovery. Wan supports adaptive and prompts up to 20000 characters; Seedance supports up to 5000, and Kling up to 2500. Resolution defaults to 720p except Kling 3.0 Omni (1080p). Seedance 2.5 defaults to 15 seconds, other Seedance models to 5 seconds. Native audio defaults to on.

The Seedance 5000-character limit is the API's validation limit, not a recommended prompt length. Keep each shot concise: preferably no more than 500 Chinese characters or 1000 English words. Longer prompts can dilute the focus and lose details. Read the live model catalog before submitting.

480p applies to Seedance and Wan AI video only. It is not available for Kling or new talking-avatar requests. Historical talking-avatar responses can still contain 480p.

Estimate AI video 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
  }
}

Reference media and generate_audio do not change the credit price. Current per-second rates include:

Use the cost endpoint for the current quote rather than caching this table indefinitely. Check your remaining balance with GET /api/v1/billing/credits.

Image, video, and audio inputs

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

The following media limits describe Seedance inputs. Wan and Kling have model-specific limits; read the capability sheet before uploading.

Configure an AI video request

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.

Model-specific input combinations

• Wan: up to 10 image, 5 video, and 5 audio references, also subject to the discovered total limit. Video and audio reference durations are each limited to 15 seconds in total; an individual longer reference is clipped to its first 15 seconds. Exceeding the aggregate limit returns 37104. Combining refs with an explicit aspect_ratio returns 400.
• Kling 3.0: refs.max=0; image-to-video accepts first_frame, but an explicit aspect_ratio in that mode returns 400.
• Kling 3.0 Omni: no first_frame; up to 7 image/video references. If refs contain video, set generate_audio=false; otherwise the request returns 400.
• Use first_frame only when discovery declares image-to-video support. Always keep first_frame and refs mutually exclusive; end_frame requires first_frame.

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": "YOUR_ASSET_ID"}], "duration_sec": 10}' https://openapi.visionstory.ai/api/v1/ai_video

Poll AI video generation status

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.

Seedance moderation is asynchronous: a rejected task resolves to failed and is refunded. Wan and Kling can reject content synchronously with HTTP 403 and code 37110 (prompt) or 37111 (image), without charging. Always handle both submission errors and the failed task state.

Failed generation refunds credits in full. The API does not automatically switch to a different model after failure; returned model_id identifies the actual model.

List and delete AI videos

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.

Use the optional status query parameter to filter by one or more comma-separated values: queued, creating, created, or failed. Omitting it keeps the existing unfiltered behavior; an unknown status returns HTTP 400.

Check AI video concurrency before submitting

Query in-flight AI video tasks with status=queued,creating:

visionstory ai-videos --status queued,creating --limit 100

page = client.list_ai_videos(status="queued,creating", limit=100)
print(page)

Follow next_cursor until it is 0 when counting tasks; a single page can undercount. The list shows current usage, not the configured limit, and does not reserve a slot. A concurrency rejection returns HTTP 429 with error.details.limit and error.details.in_flight. Wait for an in-flight task to finish, refresh the list, then retry with the same client_request_id. Other rate-limit errors may not include these concurrency fields.

Error-schema compatibility: the shared error schema currently declares details as a nullable string, while concurrency errors are documented with an object. When reading concurrency metadata, accept an object or parse a JSON-encoded string; do not assume every 429 includes these fields.

Reuse media with the Assets API

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": "YOUR_ASSET_ID",
    "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.

AI video API 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.

Rate limits, storage, and idempotency

• 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.

Related VisionStory API guides

• 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.