Generate Videos with Seedance

What you can do

Use WorldRouter’s native async task API for text-to-video, video-to-video, and image-guided Seedance generation.

Before you start

Seedance uses WorldRouter’s native async task API. Create a task, then check its status until the video is ready.

• Send text-only and reference-video requests directly.
• Upload reference images first, then use the returned asset URL in your request.

Task routes

• POST /api/v3/contents/generations/tasks
• GET /api/v3/contents/generations/tasks/{task_id}

Asset helper routes

Use these routes only for reference-image uploads:

• POST /v1/asset-groups
• POST /v1/asset-groups/{asset_group_id}/assets

Quick start flow

The asset upload step depends on what kind of reference you pass:

• Text-only or with a video reference: skip the asset step. Send the request directly.
• Relay with an image reference: upload the image through the asset helpers first; public image URLs are rejected.
• Official with a public image reference URL: send the public URL directly with an official basic model.
• Official with uploaded assets: use the official asset models and create the asset group with provider: "byteplus_official".

1. 1If you need a Relay image reference, create an asset group and upload the image through the asset helpers. If you use an Official basic model with a public image URL, skip this asset step. If you need Official uploaded assets, create the group with provider: "byteplus_official".
2. 2Create a Seedance task with POST /api/v3/contents/generations/tasks.
3. 3Check task status with GET /api/v3/contents/generations/tasks/{task_id} until the job reaches a terminal state.
4. 4Read content.video_url from the task response and download the generated video from that URL.

Supported request models

These are the request model names you should send in the model field:

Important behavior:

For text-only generation or reference-video generation, send your request directly with one of the basic or official model names above.

If you are using a reference image:

• Relay models require uploading the image first through the asset helper routes.
• Relay asset requests use the returned asset://... URL and keep the public request model as seedance-2.0 or seedance-2.0-fast.
• Official basic models can use public image URLs directly.
• Official asset models use the asset helper routes with provider: "byteplus_official", then use the returned asset://... URL with seedance-2.0-asset-official or seedance-2.0-asset-fast-official.

When you use an uploaded Relay image asset, keep the public model as seedance-2.0 or seedance-2.0-fast. When you use an uploaded Official image asset, use one of the Official asset model names.

Text-to-video

Start here if you want the simplest Seedance workflow.

This example shows the basic text-to-video flow: send a prompt, create a task, then check its progress until the video is ready.

curl -X POST "https://inference-api.worldrouter.ai/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "model": "seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "A cinematic video of a city street at sunset."
    }
  ],
  "resolution": "720p",
  "duration": 5
}'

You can start with this example as-is, then adjust the parts that matter most for your use case:

• model: choose the standard or faster generation path.
• text: describe the subject, style, setting, and motion you want.
• resolution: choose the output quality supported by the model.
• duration: choose how long the generated video should be.

Typical create response:

{
"id": "task-123",
"requestId": "req-123"
}

This response confirms that the task was created successfully. Your video is not ready yet.

Save the returned task id, then continue to Check task status.

Check task status

All Seedance requests follow the same async flow after task creation, including text-to-video, reference-video, and reference-image requests.

Use the task id returned from the create response to check whether the video is still running, has succeeded, or has failed.

curl "https://inference-api.worldrouter.ai/api/v3/contents/generations/tasks/task-123" \
-H "Authorization: Bearer your_api_key"

Typical status response:

{
"id": "task-123",
"model": "seedance-2.0",
"status": "succeeded",
"content": {
  "video_url": "https://media.example.com/seedance/output.mp4"
},
"resolution": "720p",
"duration": 5,
"usage": {
  "output_tokens": 7522
}
}

When status becomes succeeded, use content.video_url to download the final video.

WorldRouter normalizes upstream task states into:

• queued
• running
• succeeded
• failed
• cancelled
• expired

Use a reference video

Reference videos can be sent directly in the request. Unlike image references, they do not require the asset helper flow.

{
"model": "seedance-2.0",
"content": [
  {
    "type": "text",
    "text": "Keep the motion rhythm of the input video and restyle it into a cinematic tea scene."
  },
  {
    "type": "video_url",
    "role": "reference_video",
    "video_url": {
      "url": "https://example.com/input.mp4"
    }
  }
],
"resolution": "720p",
"duration": 5
}

You can customize the same core fields here as well:

• text: describe the style or transformation you want.
• video_url: provide the reference video.
• resolution: choose the output quality supported by the model.
• duration: choose the target output length.

After submitting the request, follow the same steps in Check task status to monitor the task and download the result.

Asset flow for image references

Relay image references are stricter. Public image URLs are rejected for Relay Seedance generation. If you want a Relay reference image, first upload it through the asset helper routes and then use the returned asset://... URL in your generation payload.

Official basic models can use public image URLs directly. Use this asset flow for Official only when you want uploaded Official assets and the seedance-2.0-asset-official or seedance-2.0-asset-fast-official model.

1. Create an asset group

curl -X POST "https://inference-api.worldrouter.ai/v1/asset-groups" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "seedance-demo-group",
  "description": "reference assets for a Seedance run"
}'

For Official assets, include provider: "byteplus_official":

{
"name": "seedance-official-demo-group",
"description": "official reference assets for a Seedance run",
"provider": "byteplus_official"
}

Response:

{
"id": "group-1",
"name": "seedance-demo-group",
"description": "reference assets for a Seedance run",
"provider": "clawos",
"requestId": "req-456"
}

2. Upload the reference image into that group

curl -X POST "https://inference-api.worldrouter.ai/v1/asset-groups/group-1/assets" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "reference-image",
  "description": "main character reference",
  "type": "image",
  "url": "https://example.com/reference.png"
}'

Official asset uploads use the same request body after you create an Official asset group. You may also pass moderation_strategy as Default or Skip, and project_name if your BytePlus project requires it.

Response:

{
"id": "asset-1",
"asset_group_id": "group-1",
"name": "reference-image",
"description": "main character reference",
"type": "image",
"url": "asset://asset-1",
"source_url": "https://example.com/reference.png",
"provider": "clawos",
"requestId": "req-789"
}

3. Use asset://... in the generation payload

For Relay assets, keep the public request model as seedance-2.0 or seedance-2.0-fast:

{
"model": "seedance-2.0",
"asset_group_id": "group-1",
"content": [
  {
    "type": "text",
    "text": "The reference character walks down a sunlit city street with a cinematic look."
  },
  {
    "type": "image_url",
    "role": "reference_image",
    "image_url": {
      "url": "asset://asset-1"
    }
  }
],
"resolution": "720p",
"duration": 5
}

After submitting the request, follow the same steps in Check task status to monitor the task and download the result.

For Official uploaded assets, use the Official asset model:

{
"model": "seedance-2.0-asset-official",
"asset_group_id": "group-1",
"content": [
  {
    "type": "text",
    "text": "The reference object moves through a cinematic studio scene."
  },
  {
    "type": "image_url",
    "role": "reference_image",
    "image_url": {
      "url": "asset://asset-1"
    }
  }
],
"resolution": "720p",
"duration": 5
}

Notes and limits

• Seedance requires a team-scoped key with enough available credits. Low balance returns 402 seedance_balance_too_low.
• Pending Seedance jobs per user are capped. Too many running tasks return 429 seedance_too_many_pending_tasks.
• Task reads are owner-scoped. You can only poll tasks created by the same authorized owner context.
• Asset groups and uploaded assets are also owner-scoped.
• The public task status endpoint returns metadata and content.video_url; there is no separate public /v1/videos/{id}/content download route for Seedance.

Troubleshooting

See also

• Quickstart: API key and base URL setup.
• Models: current model catalog and pricing.
• API reference: chat-completions docs for text models.