AI Video Generation API

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

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.

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.

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

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

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:

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.

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.

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

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.