Documentation

Build with the Seedance API

Generate videos and images through one asynchronous API, from your first request to a reliable production integration.

Start with your first request

Follow these steps to go from zero to your first successful generation.

Get an API key

Create a key in the Dashboard, then send it in the Authorization header.

All requests require a bearer API key. This example creates an asynchronous video task with the recommended default model.

POST /v1/videos/generations

curl https://api.seedanceapi.app/v1/videos/generations \  -X POST \  -H "Authorization: Bearer $SEEDANCE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "seedance-2-0",    "prompt": "A cinematic sunrise over a mountain lake",    "duration": 5,    "ratio": "16:9",    "resolution": "720p",    "generate_audio": true  }'

Understand the system

Learn how requests are processed and how data flows.

Task lifecycleStates, polling, and what happens after a request.Input formatsChoose between convenience fields and native content.ModelsUnderstand capabilities and model-specific contracts.

Prepare for production

Build reliable integrations with explicit failure and cost handling.

Errors and retriesClassify failures and implement safe retries.Async task contractUse the task contract to receive status updates.Pricing and creditsEstimate credits across model and output choices.Parameters and limitsValidate fields before sending production traffic.

Foundation

Authentication

Send your API key in the HTTP Authorization header. Browser sessions are only used by the Dashboard and Playground; Public API calls always use bearer authentication.

http

Authorization: Bearer $SEEDANCE_API_KEY

Core concept

Task lifecycle

Generation is asynchronous. Create a task, store its localvid_* or img_* ID, then retrieve it until it reaches a terminal state.

queuedrunningsucceededfailedcancelledexpired

Request contract

Native content and convenience fields

Send native content[] items or convenience fields such asprompt, first_frame_url, and reference URL arrays. Do not mix both formats in one request.

jsonNative content[]

{  "model": "seedance-2-0",  "content": [    { "type": "text", "text": "A product reveal in soft studio light" },    {      "type": "image_url",      "image_url": { "url": "https://example.com/reference.jpg" },      "role": "reference_image"    }  ],  "resolution": "720p"}

Reference

Public API contract

Video and image requests use managed generation infrastructure. Public model names and local task IDs remain stable even when internal routing changes.

Open the OpenAPI 3.1 specification

bashRetrieve a video task

curl https://api.seedanceapi.app/v1/videos/vid_01jx9w6n8e6r7x9m2p4q \  -H "Authorization: Bearer $SEEDANCE_API_KEY"