Seedance Native Endpoint

Overview

The Seedance native endpoint format provides direct compatibility with the Volcano Engine Seedance video generation API. Unlike the OpenAI-compatible format (/v1/videos), this format uses content arrays with typed multi-modal items, giving you finer-grained control over reference materials, audio, draft tasks, and generation parameters.

Supported Models

Model	Resolutions	Notes
`doubao-seedance-2.0`	480p, 720p, 1080p	Full feature support
`doubao-seedance-2-fast`	480p, 720p	Faster generation, lower resolution cap

Create Task

POST /api/v3/contents/generations/tasks

Request Headers

Header	Required	Example
`Content-Type`	Yes	`application/json`
`Authorization`	Yes	`Bearer <YOUR_API_KEY>`

Request Parameters

Parameter	Type	Required	Description
`model`	string	Yes	Model name: `doubao-seedance-2.0` or `doubao-seedance-2-fast`
`content`	object[]	Yes	Multi-modal input array. See content Parameter
`duration`	number	Conditional	Video duration in seconds (5–15). Required for per-second billing models
`frames`	number	Conditional	Total frame count. Alternative to `duration` for per-frame billing
`resolution`	string	No	`480p`, `720p`, `1080p` (`2-fast` only supports 480p/720p)
`ratio`	string	No	`16:9`, `9:16`, `1:1`
`seed`	number	No	Random seed. Use `-1` for random. Default: `-1`
`generate_audio`	boolean	No	Generate synchronized audio. Default: `false`
`watermark`	boolean	No	Add AI generation watermark. Default: `false`
`return_last_frame`	boolean	No	Return last frame image URL in query response. Default: `false`
`service_tier`	string	No	Service tier. Default: `default`
`execution_expires_after`	number	No	Task timeout in seconds

content Parameter

Each item in content must have a type and the corresponding payload fields:

Type	Required Fields	Description
`text`	`text`	Text prompt describing the desired video
`image_url`	`image_url.url`	Image URL, Base64 data URI, or asset ID (`asset://<ASSET_ID>`)
`video_url`	`video_url.url`	Video URL or asset ID (`asset://<ASSET_ID>`)
`audio_url`	`audio_url.url`	Audio URL, Base64 data URI, or asset ID (`asset://<ASSET_ID>`)
`draft_task`	`draft_task.id`	Reference a draft task to generate the final video

Supported content combinations:

Text
Text (optional) + Image
Text (optional) + Video
Text (optional) + Image + Audio
Text (optional) + Image + Video
Text (optional) + Video + Audio
Text (optional) + Image + Video + Audio

role Values

Type	`role`	Description
`image_url`	`first_frame`	First frame for image-to-video. Single image without role also treated as first frame
`image_url`	`last_frame`	Last frame. Requires `first_frame` alongside it
`image_url`	`reference_image`	Reference image (1–9 images for Seedance 2.0)
`video_url`	`reference_video`	Reference video (max 3, total duration ≤ 15s)
`audio_url`	`reference_audio`	Reference audio (max 3 clips, total duration ≤ 15s)

First-frame image-to-video, first-last-frame image-to-video, and multi-modal reference generation are mutually exclusive. Do not mix these modes in a single request.

Text-to-Video

curl --location --request POST 'https://api.wisgate.ai/api/v3/contents/generations/tasks' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data-raw '{
    "model": "doubao-seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "一只小猫在清晨阳光里伸懒腰，镜头缓慢推进，画面温暖自然。"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "seed": -1,
    "generate_audio": true,
    "watermark": false
  }'

Reference-to-Video

curl --location --request POST 'https://api.wisgate.ai/api/v3/contents/generations/tasks' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data-raw '{
    "model": "doubao-seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "全程使用视频1的第一视角构图，全程使用音频1作为背景音乐。第一人称视角果茶宣传广告。"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/reference.jpg" },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/reference.mp4" },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": { "url": "https://example.com/reference.mp3" },
        "role": "reference_audio"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true,
    "return_last_frame": true
  }'

First/Last Frame Image-to-Video

{
  "model": "doubao-seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "让画面从首帧自然过渡到尾帧，镜头保持平稳推进。"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.png" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last-frame.png" },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

Create Response

{
  "id": "cgt-20260518175249-8x55h"
}

Query Task

GET /api/v3/contents/generations/tasks/{id}

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Task ID returned from the create endpoint

Request Headers

Header	Required	Example
`Authorization`	Yes	`Bearer <YOUR_API_KEY>`

Query Example

curl --location --request GET 'https://api.wisgate.ai/api/v3/contents/generations/tasks/cgt-20260518175249-8x55h' \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Success Response

{
  "id": "cgt-20260518175249-8x55h",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "error": null,
  "created_at": 1778756838,
  "updated_at": 1778757081,
  "content": {
    "video_url": "https://example.com/generated-video.mp4?signature=<SIGNED_URL_PARAMS>",
    "last_frame_url": "https://example.com/last-frame.png?signature=<SIGNED_URL_PARAMS>"
  },
  "seed": 29545,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "generate_audio": true,
  "service_tier": "default",
  "execution_expires_after": 172800,
  "usage": {
    "completion_tokens": 173700,
    "total_tokens": 173700
  }
}

Response Fields

Field	Type	Description
`id`	string	Task ID
`model`	string	Actual upstream model used for generation
`status`	string	Task status: `queued`, `running`, `succeeded`, `failed`, `expired`, `cancelled`
`error`	object / null	Error details when status is `failed`
`created_at`	number	Creation timestamp (Unix seconds)
`updated_at`	number	Last update timestamp (Unix seconds)
`content.video_url`	string	Generated video URL (signed, time-limited — download promptly)
`content.last_frame_url`	string	Last frame image URL (only if `return_last_frame` was `true`)
`seed`	number	Random seed used for generation
`resolution`	string	Video resolution
`ratio`	string	Aspect ratio
`duration`	number	Video duration in seconds
`frames`	number	Frame count (per-frame billing models)
`framespersecond`	number	Frame rate (FPS)
`generate_audio`	boolean	Whether synchronized audio was generated
`service_tier`	string	Service tier used
`execution_expires_after`	number	Result retention period in seconds
`usage.completion_tokens`	number	Tokens consumed for generation
`usage.total_tokens`	number	Total token consumption

Complete Workflow

import requests
import time

BASE_URL = "https://api.wisgate.ai"
HEADERS = {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
}

# Step 1: Create task
response = requests.post(
    f"{BASE_URL}/api/v3/contents/generations/tasks",
    headers=HEADERS,
    json={
        "model": "doubao-seedance-2.0",
        "content": [{"type": "text", "text": "A cat walking on a sunny street"}],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5
    }
)
task_id = response.json()["id"]
print(f"Task created: {task_id}")

# Step 2: Poll for status and download
while True:
    result = requests.get(
        f"{BASE_URL}/api/v3/contents/generations/tasks/{task_id}",
        headers={"Authorization": HEADERS["Authorization"]}
    ).json()

    status = result["status"]
    print(f"Status: {status}")

    if status == "succeeded":
        video_url = result["content"]["video_url"]
        video = requests.get(video_url, stream=True)
        with open("generated_video.mp4", "wb") as f:
            for chunk in video.iter_content(chunk_size=8192):
                f.write(chunk)
        print("Video downloaded successfully!")
        break
    elif status in ("failed", "expired", "cancelled"):
        print(f"Task ended: {status}, Error: {result.get('error')}")
        break

    time.sleep(10)

Parameter Limits

Parameter	Supported Values
`duration`	`5` to `15` seconds
`ratio`	`16:9`, `9:16`, `1:1`
`resolution`	`480p`, `720p`, `1080p`
`content.image_url.url`	Public URL, `data:image/<format>;base64,<BASE64>`, or `asset://<ASSET_ID>`
`content.video_url.url`	Public URL or `asset://<ASSET_ID>`
`content.audio_url.url`	Public URL, `data:audio/<format>;base64,<BASE64>`, or `asset://<ASSET_ID>`

Important Notes

API Key Security Never expose real API keys in code, documentation, logs, or screenshots. Use environment variables or placeholder values.

Face Content Policy Seedance 2.0 models do not support uploading reference images or videos containing real human faces. Use platform-compliant assets, virtual avatars, or licensed materials for portrait content.

Download Promptly content.video_url is typically a signed URL with an expiration window. Download or transfer the video before it expires. Check execution_expires_after for the retention period.

Polling If the task has not completed, poll the query endpoint at intervals of several seconds. Avoid tight polling loops to prevent rate limiting.

Do not mix request body formats between /v1/videos and /api/v3/contents/generations/tasks. The prompt/size fields belong to the OpenAI-compatible format; the Seedance native format uses content/ratio/resolution.
Large files should use public URLs or asset IDs rather than Base64 encoding to keep request body sizes manageable.
If an API key is exposed or compromised, rotate or revoke it immediately.

Format Comparison

Feature	OpenAI Compatible (`/v1/videos`)	Seedance Native (`/api/v3/...`)
Content input	`prompt` + `images[]` + `videos[]`	`content[]` with typed items
Audio reference	Not supported	`audio_url` type
Draft task	Not supported	`draft_task` type
Resolution format	`1280x720`, `1920x1080`	`720p`, `1080p`, `480p`
Aspect ratio	`size` field	`ratio` field (`16:9`, `9:16`, `1:1`)
Watermark control	Not supported	`watermark` boolean
Last frame retrieval	Not supported	`return_last_frame` boolean
Seed control	Not directly exposed	`seed` field

Use the OpenAI-compatible format for simpler text-to-video and basic image/video reference scenarios. Use the Seedance native format when you need audio references, draft tasks, watermark control, or last frame retrieval.

Text Models

Image Models

Video Models

User

Error Handling

Seedance Native Endpoint

Overview

Supported Models

Create Task

Request Headers

Request Parameters

content Parameter

role Values

Text-to-Video

Reference-to-Video

First/Last Frame Image-to-Video

Create Response

Query Task

Path Parameters

Request Headers

Query Example

Success Response

Response Fields

Complete Workflow

Parameter Limits

Important Notes

Format Comparison

Text Models

Image Models

Video Models

User

Error Handling

Documentation Index

​Overview

​Supported Models

​Create Task

​Request Headers

​Request Parameters

​content Parameter

​role Values

​Text-to-Video

​Reference-to-Video

​First/Last Frame Image-to-Video

​Create Response

​Query Task

​Path Parameters

​Request Headers

​Query Example

​Success Response

​Response Fields

​Complete Workflow

​Parameter Limits

​Important Notes

​Format Comparison

Overview

Supported Models

Create Task

Request Headers

Request Parameters

content Parameter

role Values

Text-to-Video

Reference-to-Video

First/Last Frame Image-to-Video

Create Response

Query Task

Path Parameters

Request Headers

Query Example

Success Response

Response Fields

Complete Workflow

Parameter Limits

Important Notes

Format Comparison