REST API documentation
Everything you need to integrate Seedance 2.5 into your project. Code samples use this deployment's base URL.
Quickstart #
Get an API key vg_live_… from the Vidgen admin, then create your first job and poll for the result. Three steps:
- Store the key in an environment variable (
VIDGEN_API_KEY), never in public client code. POST /api/v1/generate→ receivejob.id(HTTP 202).- Poll
GET /api/v1/jobs/{id}untilsucceeded, then readresult.url.
Authentication #
Every request to /api/v1/* endpoints (except models/stats/health/meta) uses an API key. Three equivalent ways:
| Method | Example |
|---|---|
| Authorization | Authorization: Bearer vg_live_… |
| Header | x-api-key: vg_live_… |
| Query | ?api_key=vg_live_… (avoid in public logs) |
Revoked or invalid keys return 401 invalid_api_key. For the web dashboard, sign in with the same key via POST /api/auth/login. The session is kept in an HttpOnly cookie for 30 days on that browser, so you do not need to enter the key on every visit. The raw key is never stored in localStorage or rendered in the page.
Models & capabilities #
GET /api/v1/modelsReturns the model catalog with valid parameters and default values. No auth required.
| Parameter | Valid values | Default |
|---|---|---|
| duration | 30 (seconds) | 30 |
| resolution | 480p, 720p, 1080p | 720p |
| ratio | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 | 16:9 |
| ttl | 1d, 7d, 30d | 30d |
| image_urls | 0–9 images (1 = start frame, 2–9 = references) | — |
How capacity works #
Vidgen runs a configurable pool of session slots (default 20, scalable to 100). You always submit to one endpoint; the scheduler assigns every job to the least-loaded slot automatically. Capacity has three layers: concurrency, queue, and daily quota.
| Layer | Limit | What it means |
|---|---|---|
| Concurrency | 8 jobs per slot | Active slots × 8 jobs run at the same time. |
| Queue | 100 jobs total | One global queue shared by all slots. Beyond 100 waiting jobs, 429 queue_full. |
| Daily quota | 35 generations per slot/day | Aggregate quota follows the number of active slots. Concurrency does not increase it. |
| Per API key | 160 active + queued jobs | Per-key cap; 429 key_queue_full when reached. |
Only active slots count. A slot is usable when its session is active. If 10 slots are active, effective concurrency is 80 jobs (10 × 8), the queue stays 100 jobs total, and daily quota is 350 generations/day (10 × 35). Inactive slots receive no work. Activating a slot later makes it available for new jobs immediately, but jobs already queued are not rebalanced automatically.
Breadth-first allocation. With N active slots, the scheduler first gives every slot one job before adding a second job to any slot.
| Jobs submitted | Distribution |
|---|---|
| 1–N | 1 job per active slot |
| N+1–2N | 2 jobs per slot |
| 2N+1–3N | 3 jobs per slot |
| Up to 8N | 8 jobs per slot (maximum concurrency) |
| Beyond 8N | Queued globally (maximum 100 waiting jobs) |
Queue and drain worker. When every active slot is at 8 concurrent jobs, new jobs wait in one global queue capped at 100. Each queued job is assigned to the least-loaded slot; the drain worker takes the oldest queued job on a slot as soon as that slot frees up, skips slots whose daily quota is exhausted, polls job status every 5 seconds, and retries transient engine errors up to 3 attempts.
Job lifecycle. queued → dispatching → processing → succeeded or failed. A queued job can be cancelled; a processing job cannot. Jobs that do not finish within 120 minutes are marked failed.
idempotencyKey for safe retries, prefer webhooks for high volume, poll every 4–10 seconds, and keep queuePosition as an estimate rather than a guarantee. Results are stored for 30 days. 720p is the most reliable resolution; reference images with real human faces are rejected by moderation.Create job #
POST /api/v1/generateCreates a single generation job. Returns 202 before the result is ready; fetch the result via polling or webhook. Idempotent replays return 200.
| Field | Type | Description |
|---|---|---|
| model | string | Required. seedance-2.5 (aliases accepted). |
| prompt | string | Required, ≤15,000 characters. |
| parameters.duration | string/int | 30 (seconds); a trailing s is accepted. |
| parameters.resolution | string | 480p/720p/1080p. |
| parameters.ratio | string | Alias: aspect_ratio. |
| ttl | string | 1d/7d/30d; alias storage_ttl. Results are always stored for 30 days. |
| image_urls | string[] | Optional. 1 image = start frame (I2V); 2–9 images = references (R2V). |
| image_url | string | Alias for a single image URL. |
| webhook_url | string | Optional. Result notification target. |
| idempotencyKey | string | Optional, ≥8 characters; prevents duplicate jobs. |
sourceAssetId). 2–9 images = multi-reference video (R2V, sent as refAssetIds). End-frame mode is not supported. Images depicting real people may be rejected by content moderation; stylized characters and animals are supported.image_url or image_urls). Video files are not accepted as references yet. Reliable reference settings: 720p, 9:16, up to 2 reference images. Avoid 480p or 21:9 with references, 4+ reference images, and real human faces — the engine may reject these combinations.429 key_queue_full) and 60 generate requests/minute/IP. Global queue full → 429 queue_full; no ready slots → 503 no_slot.Job status #
GET /api/v1/jobs/{id}Returns the latest job state. Polling this endpoint also triggers a background check, so polling is the only signal you need. Only the owner can read a job (403 for other keys).
| Field | Description |
|---|---|
| status | queued · dispatching · processing · succeeded · failed · cancelled |
| queuePosition | Queue position; only while queued, otherwise null. |
| progress | 0–100. |
| durationSeconds | Total seconds from creation to finish; null while the job is not finished. |
| referenceCount | Number of reference images (0 = T2V, 1 = start frame, 2–9 = R2V). |
| duration · resolution · ratio · ttl | Job parameters: duration (seconds), resolution, ratio, and result TTL. |
| result | null until success; then {url, expiresAt, ttl}. |
| errorMessage | Failure description (sanitized); null unless failed. |
List & cancel jobs #
GET /api/v1/jobs DELETE /api/v1/jobs/{id}Lists jobs owned by your key, newest first. Query: status, limit (≤50), offset. You can only cancel a job while it is queued; jobs already processing return 409 not_cancellable, finished jobs return 409 already_finished.
Profile & usage #
GET /api/v1/meAPI key profile (masked), 24-hour / 7-day / 30-day usage, and active limits. Useful for reseller dashboards.
Webhooks #
When a job has a webhook_url, we send a POST on video.succeeded or video.failed. The payload contains event, job (public shape), and sentAt.
| Header | Value |
|---|---|
| X-Vidgen-Event | video.succeeded / video.failed |
| X-Vidgen-Signature | sha256=<HMAC-SHA256(secret, body)> |
| User-Agent | VidgenWebhook/1.0 |
Verify the signature before processing. We retry twice with a delay; webhook failures do not cancel the job.
Storage & TTL #
Video results are uploaded to TTL-backed storage and the original URL is replaced with a direct file link. Results are retained for 30 days; the ttl field is still accepted for compatibility. The result.expiresAt field gives the exact expiry time in ISO format.
expiresAt, the link is no longer valid. Download or move the video to your own storage before it expires. If primary storage fails, we use a temporary 24-hour TTL fallback.Idempotency #
Send an idempotencyKey (≥8 characters) to make retries safe. The same key returns the existing job with 200 and idempotent: true — no new job. Values under 8 characters are ignored.
Errors & rate limits #
All errors have the shape { success:false, error, code, … }. Messages are sanitized and written in neutral English.
| HTTP | code | Situation |
|---|---|---|
| 400 | invalid_parameter | Invalid model/prompt/duration/resolution/ratio/ttl/URL. |
| 401 | invalid_api_key | Key is invalid or revoked. |
| 403 | forbidden | Job belongs to another key. |
| 404 | not_found | Job/endpoint does not exist. |
| 409 | not_cancellable / already_finished | Cancel a job that is processing/finished. |
| 413 | payload_too_large | Request body exceeds the 1 MB limit. |
| 429 | key_queue_full / queue_full | Per-key job limit / global queue is full. |
| 429 | (rate limit) | Generate 60/minute/IP; login 20/10 minutes/IP. |
| 503 | no_slot | No slot is ready yet. |
Stats & health #
GET /api/v1/stats GET /api/v1/live GET /api/v1/healthstats = capacity, daily quota, and success snapshot; live = Server-Sent Events (event stats) for real-time dashboards; health = operational status for uptime monitors. All public.
Integration examples #
Common pattern: create a job → poll or receive a webhook → deliver the result to the user. Below: a Telegram bot (Node) and a call from a SaaS web app.