Create Task (Volc Compatible)

OverviewCopy Anchor Link

Existing Volc-style Seedance clients can use TokenLab by changing the API address and key.

See also Seedance 2.0 Video Models and Video Generation.

Authentication And EndpointsCopy Anchor Link

• Use Authorization: Bearer <TOKENLAB_API_KEY>.
• Volc AK/SK signing is not accepted. Requests must include a TokenLab Bearer key.
• Use the official task path: POST /api/v3/contents/generations/tasks.

Content RulesCopy Anchor Link

• type: "text" is the prompt text.
• type: "image_url" without role, or with role: "first_frame", is treated as the first frame.
• role: "last_frame" must be paired with a first frame.
• role: "reference_image", reference_video, and reference_audio are used as references.
• image_url.url accepts a public image URL or a material URI such as asset://asset-YYYYMMDDHHMMSS-xxxxx. The role determines whether that material is a first frame, last frame, or reference image.
• Do not mix first/last frame inputs with reference media in one request.
• Top-level material_asset_id and material_asset_ids are rejected. Put a TokenLab material URI in image_url.url. priority is supported only for Seedance 2.5.

Parameter NotesCopy Anchor Link

duration is an integer number of seconds; -1 selects automatic duration. Defaults and limits differ by model:

For Seedance 2.5, first-frame, first/last-frame, video extension, and video-to-video requests require ratio: "adaptive"; video-to-video also requires duration: -1. output_format accepts mp4 or mov only for Seedance 2.5.

• ratio accepts 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, or adaptive.
• watermark, return_last_frame, seed, execution_expires_after, and safety_identifier are accepted when valid for the selected model.
• callback_url may point to a public HTTP(S) endpoint.

Callback DeliveryCopy Anchor Link

When callback_url is present, TokenLab sends an HTTP POST when task status changes. Callback statuses are queued, running, succeeded, failed, and expired. The JSON body matches the get-task response.

A 2xx response acknowledges delivery. For succeeded and failed, a delivery that does not succeed within five seconds is retried up to three times. The callback has only the standard JSON content header and no TokenLab-specific delivery headers. Redirects are not followed, and private or reserved network targets are rejected.

Save the task ID. If a callback is not delivered, you can still retrieve the result with the get-task endpoint.

Image PreparationCopy Anchor Link

Public HTTP(S) image URLs and supported data URLs are used as supplied; they are not automatically saved as reusable materials. Explicit asset://asset-... references use existing TokenLab materials. TokenLab checks ownership and readiness before generation. If a referenced material is still preparing, wait until it is ready and retry; inspect error.code and error.message when creation fails.

For existing materials, use the public asset-YYYYMMDDHHMMSS-xxxxx ID rather than an original asset ID returned by another system. TokenLab verifies material ownership before generation.

Create ResponseCopy Anchor Link

{
  "id": "cgt-20260102030405-a1b2c"
}

The create response contains only the task ID. Save it so you can retrieve status and results at any time.

Prevent Duplicate TasksCopy Anchor Link

Send a unique Idempotency-Key with create requests. If the connection closes before the response arrives, retry with the same API key, idempotency key, and request body:

• If the original task was created, TokenLab returns the same cgt-... ID and adds Idempotency-Replayed: true.
• If the original request is still being registered, TokenLab returns 409 IdempotencyRequestInProgress; retry later with the same key and body.
• Reusing the key with a different body returns 409 IdempotencyConflict and never creates a second task.

Idempotency applies to the official v3 REST create path. It does not change the JSON response shape, and it is not inferred from X-Request-ID or from identical request bodies without a key.

ExampleCopy Anchor Link

REST CreateCopy Anchor Link

curl https://api.tokenlab.sh/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

For existing materials, put each URI in the official content[] item and declare its role:

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

Next StepCopy Anchor Link

Use the returned cgt-... ID with Get Task (Volc Compatible) until the task reaches a terminal status.

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'

{  "id": "string"}