Seedance 2.0 Relay API Documentation

Seedance 2.0 中转站为 B 端客户提供与火山引擎 Seedance 2.0 官方 API 完全兼容的代理接口。
您只需将 Base URL 和 API Key 替换为中转站分配的地址和 Relay Key，其余请求格式完全一致。

Compatibility

中转站 API 与火山引擎 Seedance 2.0 官方 API 完全兼容。您现有的代码只需修改两处：

// Before (direct Volcengine)
baseURL: "https://ark.cn-beijing.volces.com/api/v3"
Authorization: Bearer <Volcengine API Key>

// After (via Relay)
baseURL: "https://your-host/relay/v3"
Authorization: Bearer rk-xxxxxxxx

Quick Start

3 步快速接入：

Minimal Example (cURL)

# Step 1: Create video generation task
curl -X POST https://your-host/relay/v3/contents/generations/tasks \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [{"type": "text", "text": "A cat yawning on a balcony in warm sunlight"}],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }'

# Response: {"id": "cgt-xxxxxxxxxxxx-xxxxx"}

# Step 2: Poll task status (repeat until status is terminal)
curl https://your-host/relay/v3/contents/generations/tasks/cgt-xxxxxxxxxxxx-xxxxx \
  -H "Authorization: Bearer rk-your-relay-key"

# Response when done: {"status": "succeeded", "content": {"video_url": "https://..."}, ...}

Authentication

所有请求必须在 HTTP Header 中携带 Relay Key：

Process Flow

Video Generation Flow

Asset + Video Generation Flow

Error Codes

All responses follow a unified format:

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Quota exceeded or account inactive"
  }
}

Relay Errors

Upstream Errors (from Volcengine)

When the upstream Volcengine API returns an error, the relay forwards the original response body as-is. Common Seedance errors:

Quota & Rate Limit

Each relay account has configurable quotas:

When a quota limit is reached, the API returns 429 QUOTA_EXCEEDED. Concurrent task count is automatically decremented when a task reaches a terminal state (succeeded/failed/expired/cancelled) via the query endpoint.

Create Video Generation Task

Create a Seedance 2.0 video generation task. Supports text-to-video, image-to-video (first frame / first+last frame), and multimodal reference generation.

Request Body

Content Items

Response

{
  "id": "cgt-20260601120000-xxxxx"
}

Returns a task ID. Use the Query Task endpoint to poll for results.

Available Models

You may also use a custom Endpoint ID (e.g. ep-20260528xxxxxx-xxxxx) if configured by the admin.

Query Task Status

Poll the status of a video generation task. Keep polling until the status is terminal.

Path Parameters

Response (Running)

{
  "id": "cgt-20260601120000-xxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "running"
}

Response (Succeeded)

{
  "id": "cgt-20260601120000-xxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-prod-asset.tos-cn-beijing.volces.com/...",
    "last_frame_url": "https://..."
  },
  "usage": {
    "completion_tokens": 50638,
    "total_tokens": 50638
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "seed": 37072,
  "generate_audio": true
}

Task Status Values

List Available Models & Endpoints

Query the available models and endpoints for your relay account. Useful for discovering which models/endpoints are configured.

Response

{
  "success": true,
  "data": {
    "allowed_models": ["ep-20260528130905-bjj8g"],
    "endpoints": [
      {
        "id": "ep-20260528130905-bjj8g",
        "name": "seedance-2.0-fast",
        "status": "Running",
        "model_name": "doubao-seedance-2-0-fast",
        "model_version": "260128",
        "description": "Fast model endpoint"
      }
    ]
  }
}

allowed_models: If non-empty, only these model IDs / endpoint IDs are allowed for this account.
endpoints: All endpoints visible to the account's IAM sub-user. Status Running means the endpoint is active.

Asset Library Overview

The Asset Library allows you to upload personal images/videos as assets for use in Seedance 2.0 video generation (e.g., virtual avatar, reference footage). Assets are organized into Asset Groups.

Asset Usage in Video Generation

Once an asset is uploaded and in active status, use its ID in the video generation prompt:

{
  "content": [
    { "type": "image_url", "image_url": { "url": "asset://asset-20260601-xxxxx" } },
    { "type": "text", "text": "The person in image 1 is dancing in the rain" }
  ]
}

Asset Requirements

Create Asset Group

Create a group to organize related assets (e.g., all assets for one virtual character).

Request Body

Response

{
  "ResponseMetadata": { ... },
  "Result": {
    "Id": "group-20260601-xxxxx"
  }
}

List Asset Groups

Request Body

Request Example

{
  "Filter": { "GroupType": "AIGC" },
  "PageNumber": 1,
  "PageSize": 10
}

Create Asset (Upload)

Upload an asset (image/video/audio) to an asset group. This is an asynchronous API — the asset will be in processing status initially.

Request Body

Response

{
  "ResponseMetadata": { ... },
  "Result": {
    "Id": "asset-20260601-xxxxx",
    "Status": "Processing"
  }
}

Get Asset

Query asset status and details. Poll until status is Active before using in video generation.

Response (Active)

{
  "ResponseMetadata": { ... },
  "Result": {
    "Id": "asset-20260601-xxxxx",
    "Status": "Active",
    "AssetType": "Image",
    "PreviewUrl": "https://..."
  }
}

Asset status values: Processing → Active (ready to use) or Failed.

Example: Text to Video

// POST /relay/v3/contents/generations/tasks
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "A golden retriever running on a beach at sunset, cinematic, slow motion, 4K quality"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true
}

Example: Image to Video (First Frame)

// POST /relay/v3/contents/generations/tasks
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.jpg" }
    },
    {
      "type": "text",
      "text": "The camera slowly zooms in, the person smiles and waves"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}

Example: Asset-Based Video Generation

Use an uploaded virtual avatar asset as reference:

// Step 1: Upload asset (after creating group)
// POST /relay/v3/assets
{
  "GroupId": "group-20260601-xxxxx",
  "URL": "https://example.com/portrait.jpg",
  "AssetType": "Image"
}
// Response: { "Result": { "Id": "asset-20260601-xxxxx" } }

// Step 2: Wait for asset to be Active (poll GET /relay/v3/assets/asset-xxx)

// Step 3: Generate video using asset
// POST /relay/v3/contents/generations/tasks
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "image_url",
      "image_url": { "url": "asset://asset-20260601-xxxxx" },
      "role": "reference_image"
    },
    {
      "type": "text",
      "text": "The person in image 1 is giving a keynote speech on stage"
    }
  ],
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9"
}

cURL Examples

Create Task

curl -X POST https://your-host/relay/v3/contents/generations/tasks \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [{"type": "text", "text": "A futuristic city at night with flying cars"}],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }'

Query Task

curl https://your-host/relay/v3/contents/generations/tasks/cgt-xxxxx \
  -H "Authorization: Bearer rk-your-relay-key"

List Models

curl https://your-host/relay/v3/models \
  -H "Authorization: Bearer rk-your-relay-key"

List Asset Groups

curl -X POST https://your-host/relay/v3/assets/groups/list \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{"Filter": {"GroupType": "AIGC"}, "PageNumber": 1, "PageSize": 10}'

Create Asset Group

curl -X POST https://your-host/relay/v3/assets/groups \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{"Name": "My Character", "GroupType": "AIGC"}'

Upload Asset

curl -X POST https://your-host/relay/v3/assets \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-xxxxx",
    "URL": "https://example.com/portrait.jpg",
    "AssetType": "Image"
  }'