---
title: "Create Seedance task (Volc wire-compatible)"
method: POST
path: "/api/v3/contents/generations/tasks"
tags: ["Seedance Volc Compatible"]
---

# Create Seedance task (Volc wire-compatible)

`POST /api/v3/contents/generations/tasks`

## Request

- Base URL: `https://api.tokenlab.sh`
- URL: `https://api.tokenlab.sh/api/v3/contents/generations/tasks`
- Auth: HTTP bearer

Creates a Seedance 2.0 video task with the official Volc REST body and response shape. Authentication uses a TokenLab Bearer API key. TokenLab additionally accepts an optional Idempotency-Key header so a client can recover the same task ID after a lost create response.

## Headers

- `X-TokenLab-Delivery-Policy` 'auto' | 'verified' | 'official'
- `Idempotency-Key` string

## Request body

- VolcSeedanceCreateTaskRequest
  - `model` string, required: Seedance model or endpoint identifier. TokenLab maps supported Seedance 2.0 identifiers to the matching platform model.
  - `content` VolcSeedanceContentItem[], required: At most 16 content items: one text item, nine image_url items, three video_url items, three audio_url items, and one draft_task item. Model- and operation-specific combination rules still apply.
    - `type` 'text' | 'image_url' | 'video_url' | 'audio_url' | 'draft_task', required
    - `text` string: Text prompt content. Required when type=text.
    - `role` 'first_frame' | 'last_frame' | 'reference_image' | 'reference_video' | 'reference_audio': Media role. first_frame/last_frame inputs cannot be mixed with reference_image/reference_video/reference_audio inputs.
    - `image_url` object: Image reference in the official {"url":"https://..."} shape. TokenLab material URIs remain available as URL values without changing the request object shape.
      - `url` string, required
    - `video_url` object: Video URL. Use role=reference_video.
      - `url` string, required
    - `audio_url` object: Audio URL. Use role=reference_audio.
      - `url` string, required
    - `draft_task` object: Draft task reference in the official {"id":"cgt-..."} shape.
      - `id` string, required
  - `ratio` '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | '21:9' | 'adaptive': Output aspect ratio. Defaults to adaptive when omitted.
  - `duration` union: Video duration in seconds. Seedance 2.0 supports normal integer durations and -1 for automatic duration where the selected model supports it.
    - -1
    - integer
  - `resolution` '480p' | '720p' | '1080p': Requested output resolution. Model-specific availability still applies.
  - `generate_audio` boolean: Whether to generate synchronized audio. The official default is false.
  - `return_last_frame` boolean: Return the final frame URL when supported.
  - `watermark` boolean
  - `seed` integer: Random seed. -1 lets the model choose a seed. Accepted on a best-effort basis where supported by the model.
  - `execution_expires_after` integer: Task execution expiration window in seconds.
  - `safety_identifier` string: Stable caller-side safety identifier.
  - `service_tier` 'default' | 'flex': default is accepted. flex is rejected for Seedance 2.0 compatibility tasks because the selected model family does not support it here.
  - `tools` object[]: Optional tools such as {"type":"web_search"} when supported by the selected model.
    - `type` 'web_search', required
  - `draft` boolean: draft=true is not supported for Seedance 2.0 compatibility tasks and is rejected.
  - `frames` integer: Not supported for Seedance 2.0 compatibility tasks. Use duration instead.
  - `camera_fixed` boolean: camera_fixed=true is not supported for Seedance 2.0 compatibility tasks. false is accepted as a no-op.
  - `callback_url` string, uri: Public HTTP(S) endpoint notified by POST whenever status changes. The body is identical to the get-task response. queued, running, succeeded, failed, and expired are delivered. For succeeded and failed, a delivery without success within 5 seconds is retried up to three times.

## Response `200`

Task created

- VolcSeedanceCreateTaskResponse
  - `id` string, required

## Other responses

- `400`: Invalid request
- `401`: Missing or unsupported authentication
- `409`: Idempotency key conflict or original request still in progress
- `500`: Internal error
- `503`: The requested Delivery tier is temporarily unavailable.

---

[API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)