Vidgen Seedance 2.5 API
API Reference

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:

  1. Store the key in an environment variable (VIDGEN_API_KEY), never in public client code.
  2. POST /api/v1/generate → receive job.id (HTTP 202).
  3. Poll GET /api/v1/jobs/{id} until succeeded, then read result.url.
Need the model list and valid parameters? See Models & capabilities. Video results are TTL-backed — download or save them before they expire.

Authentication #

Every request to /api/v1/* endpoints (except models/stats/health/meta) uses an API key. Three equivalent ways:

MethodExample
AuthorizationAuthorization: Bearer vg_live_…
Headerx-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/models

Returns the model catalog with valid parameters and default values. No auth required.

ParameterValid valuesDefault
duration30 (seconds)30
resolution480p, 720p, 1080p720p
ratio16:9, 9:16, 1:1, 4:3, 3:4, 21:916:9
ttl1d, 7d, 30d30d
image_urls0–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.

LayerLimitWhat it means
Concurrency8 jobs per slotActive slots × 8 jobs run at the same time.
Queue100 jobs totalOne global queue shared by all slots. Beyond 100 waiting jobs, 429 queue_full.
Daily quota35 generations per slot/dayAggregate quota follows the number of active slots. Concurrency does not increase it.
Per API key160 active + queued jobsPer-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 submittedDistribution
1–N1 job per active slot
N+1–2N2 jobs per slot
2N+1–3N3 jobs per slot
Up to 8N8 jobs per slot (maximum concurrency)
Beyond 8NQueued 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.

Planning tips. Use 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/generate

Creates a single generation job. Returns 202 before the result is ready; fetch the result via polling or webhook. Idempotent replays return 200.

FieldTypeDescription
modelstringRequired. seedance-2.5 (aliases accepted).
promptstringRequired, ≤15,000 characters.
parameters.durationstring/int30 (seconds); a trailing s is accepted.
parameters.resolutionstring480p/720p/1080p.
parameters.ratiostringAlias: aspect_ratio.
ttlstring1d/7d/30d; alias storage_ttl. Results are always stored for 30 days.
image_urlsstring[]Optional. 1 image = start frame (I2V); 2–9 images = references (R2V).
image_urlstringAlias for a single image URL.
webhook_urlstringOptional. Result notification target.
idempotencyKeystringOptional, ≥8 characters; prevents duplicate jobs.
Reference modes. 0 images = text-to-video (T2V). 1 image = start frame (I2V, sent as 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.
Reference input. Reference assets must be image URLs (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.
Limit of 160 active+queued jobs per API key (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).

FieldDescription
statusqueued · dispatching · processing · succeeded · failed · cancelled
queuePositionQueue position; only while queued, otherwise null.
progress0–100.
durationSecondsTotal seconds from creation to finish; null while the job is not finished.
referenceCountNumber of reference images (0 = T2V, 1 = start frame, 2–9 = R2V).
duration · resolution · ratio · ttlJob parameters: duration (seconds), resolution, ratio, and result TTL.
resultnull until success; then {url, expiresAt, ttl}.
errorMessageFailure 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/me

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

HeaderValue
X-Vidgen-Eventvideo.succeeded / video.failed
X-Vidgen-Signaturesha256=<HMAC-SHA256(secret, body)>
User-AgentVidgenWebhook/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.

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

HTTPcodeSituation
400invalid_parameterInvalid model/prompt/duration/resolution/ratio/ttl/URL.
401invalid_api_keyKey is invalid or revoked.
403forbiddenJob belongs to another key.
404not_foundJob/endpoint does not exist.
409not_cancellable / already_finishedCancel a job that is processing/finished.
413payload_too_largeRequest body exceeds the 1 MB limit.
429key_queue_full / queue_fullPer-key job limit / global queue is full.
429(rate limit)Generate 60/minute/IP; login 20/10 minutes/IP.
503no_slotNo slot is ready yet.

Stats & health #

GET /api/v1/stats GET /api/v1/live GET /api/v1/health

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

Production ready? Keep the key on your server, use an idempotency key for retries, and verify webhooks. Need a key? Sign in or contact the Vidgen admin.