Public API

Build video generation into your own product

Create a secure API key, submit Seedance video jobs with Bearer authentication, and poll each task until the stored result is ready.

Manage keys

Quickstart

Create a key

Generate a key in account settings. The full secret is shown only once.

Submit a job

Send a POST request with Bearer auth and a unique Idempotency-Key.

Poll the result

Query the task until its status becomes completed or failed.

Authentication

Every request must include the API key in the Authorization header. Keep keys on your server and never embed them in browser or mobile bundles.

http

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
Idempotency-Key: a-unique-id-per-request

API keys are hashed at rest and can be revoked instantly.

Seedance video generation

Text-to-video, first/last-frame image-to-video, and typed reference-media workflows share one asynchronous endpoint.

POST/api/v1/video/generations

Parameters

Parameter	Type	Required	Default	Description
`mode`	string	No	text-to-video	text-to-video · image-to-video · media-to-video
`model`	string	No	seedance-2.0-fast	seedance-2.0 · seedance-2.0-fast · seedance-2.0-mini
`prompt`	string	Yes	—	3–4000 characters
`aspect_ratio`	string	No	16:9	1:1 · 21:9 · 4:3 · 3:4 · 16:9 · 9:16 · adaptive
`duration`	number	No	5	4–15 seconds
`resolution`	string	No	720p	Availability depends on model
`image_url`	HTTPS URL	Image mode	—	Opening frame; securely ingested
`end_image_url`	HTTPS URL	No	—	Optional closing frame
`reference_image_urls`	string[]	No	[]	Up to 8 public HTTPS URLs
`reference_video_urls`	string[]	No	[]	Up to 3 public HTTPS URLs
`reference_video_durations`	number[]	With reference videos	—	One whole-second value per URL; must match the fully decoded server measurement
`generate_audio`	boolean	No	true	Generate an audio track
`seed`	integer	No	—	-1 to 4294967295

Paid credits are atomically reserved before remote media is downloaded. All input media combined is limited to 256 MB. Reference videos are fully decoded to verify duration and dimensions, then inputs are copied to managed storage before provider submission. Failures confirmed before provider acceptance refund the reservation and delete inputs uploaded during that attempt. If provider acceptance is uncertain, the task, credits, and managed inputs are held for reconciliation: retry only with the same Idempotency-Key and never create a new key for that request. Completed output is always copied to Seedance-managed storage. image-to-video accepts only frame fields; media-to-video accepts only typed reference fields.

Request

bash

curl -X POST https://seedancetovideo.com/api/v1/video/generations \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-demo-001" \
  -d '{
    "mode": "text-to-video",
    "model": "seedance-2.0-fast",
    "prompt": "A cinematic glass train crossing a snowy mountain bridge",
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

Response 202

json

{
  "id": "idem_a3f8...",
  "status": "processing",
  "model": "seedance-2.0-fast",
  "mode": "text-to-video",
  "credits_used": 250,
  "credits_refunded": 0,
  "output": null,
  "error": null
}

Check task status

Poll this endpoint at a reasonable interval. Task status is processing, completed, or failed.

bash

curl https://seedancetovideo.com/api/v1/tasks/idem_a3f8... \
  -H "Authorization: Bearer $SEEDANCE_API_KEY"

Response 200

json

{
  "id": "idem_a3f8...",
  "status": "completed",
  "model": "seedance-2.0-fast",
  "mode": "text-to-video",
  "credits_used": 250,
  "credits_refunded": 0,
  "output": {
    "video_url": "https://cdn.seedancetovideo.com/...mp4"
  },
  "error": null,
  "created_at": "2026-07-13T10:00:00.000Z",
  "updated_at": "2026-07-13T10:03:12.000Z"
}

Credit pricing

API calls spend the key owner’s paid personal credits. Promotional credits are not used. Website and API purchases share the same paid balance.

Standard output pricing

Model	480p / sec	720p / sec	1080p / sec	4K / sec
`seedance-2.0`	30 credits	60 credits	150 credits	350 credits
`seedance-2.0-fast`	25 credits	50 credits	—	—
`seedance-2.0-mini`	15 credits	30 credits	—	—

Reference-video pricing

When reference videos are used, billing is (output seconds + fully decoded, server-measured reference-video seconds) × the rate for the requested output resolution. reference_video_durations is required for pre-download reservation and must match the measurement.

Example: seedance-2.0-fast at 720p with 5s output and 3s reference video costs (5 + 3) × 30 = 240 credits.

Model	480p / sec	720p / sec	1080p / sec	4K / sec
`seedance-2.0`	20 credits	40 credits	100 credits	200 credits
`seedance-2.0-fast`	15 credits	30 credits	—	—
`seedance-2.0-mini`	10 credits	20 credits	—	—

Check paid balance with GET /api/v1/credits.

Errors

All errors use one predictable JSON envelope.

json

{
  "error": {
    "code": "invalid_request",
    "message": "prompt must contain between 3 and 4000 characters."
  }
}

Code	HTTP	Meaning
`unauthorized`	401	Missing, invalid, expired, or revoked API key.
`invalid_request`	400	Invalid body, parameter, task id, or media URL.
`insufficient_credits`	402	Not enough paid credits for the request.
`not_found`	404	Task missing or owned by another account.
`idempotency_conflict`	409	The key was reused with a different body.
`payload_too_large`	413	The JSON request exceeds 64 KiB.
`rate_limited`	429	More than 30 requests per 60 seconds for this key.
`service_busy`	503	Temporary or uncertain provider state. Retry only with the same Idempotency-Key.
`internal_error`	500	Unexpected server-side failure.

Use with Codex, Claude Code, or any agent

Give your coding agent the machine-readable documentation and let it wire the integration against the same public contract.

Open llms.txt Open OpenAPI

Frequently asked questions

Who can use the API?

Any signed-in account can create a key. Calls require enough paid credits.

Do I need a separate API subscription?

No. Create keys for free, then use subscriptions or one-time credit packs to fund calls.

Are website and API credits shared?

Paid personal credits are shared. Free signup or promotional credits are excluded from API usage.

What happens when generation fails?

Eligible confirmed failures automatically return reserved credits and report credits_refunded. If provider acceptance is uncertain, credits stay reserved while the task is reconciled; retry only with the same Idempotency-Key.

What is the rate limit?

Each API key can make up to 30 authenticated requests per 60 seconds. A 429 response includes Retry-After.

How long are output URLs retained?

Hosted URLs are delivery URLs, not a permanent archive. Copy completed outputs to your own storage promptly.

How are breaking changes released?

The current contract is versioned under /api/v1. Incompatible changes will use a new versioned base path and be published in the developer documentation.

API keys are hashed at rest and can be revoked instantly.

API usage is subject to our Terms of Service · Acceptable Use Policy · Refund Policy · Contact support.