Seedance 2.5

Seedance 2.5 is ByteDance's newest video generation model (Dreamina Seedance 2.5). Send the official ModelArk task body to POST /v1/videos/generations, keep the returned task ID, and read the finished video from GET /v1/tasks/{id}. Images, videos and audio go in content as URLs.

Model IDs

See the pricing page for current prices.

Quick example

curl https://api.toklab.ai/v1/videos/generations \
  -H "Authorization: Bearer $TOKLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5",
    "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

Endpoint

POST https://api.toklab.ai/v1/videos/generations

The body is the official ModelArk "create a video generation task" request body; this is the same endpoint every TokLab video model uses. The response is the new task (id, status: "processing"), not the finished video. Keep API keys in server-side code.

Parameters

content items

Unknown fields are rejected. Not supported: seed, callback_url (poll the task instead), tools, and the 1.x-only frames and camera_fixed. Tasks cannot be cancelled or deleted.

Modes

The mode follows from the content items; there is no mode parameter.

First-frame modes cannot be combined with reference items. With several images or any other media, every image needs a role.

Reference example

curl https://api.toklab.ai/v1/videos/generations \
  -H "Authorization: Bearer $TOKLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5",
    "content": [
      {"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": 8
  }'

Replace the example URLs with your own accessible files.

Media inputs

This API accepts URL references only. Base64, data: URLs, asset:// IDs and multipart uploads are not accepted.

Media must be public HTTP(S) URLs and meet the model's official limits:

Reference images and videos that contain real human faces are not supported by the model.

Media is checked when the task starts, before any generation. A task whose media breaks one of these limits ends as failed with invalid_request_error and a message naming the rule, for example The request was rejected: content reference videos must total at most 15 seconds., and is not charged. A file that cannot be read at that point is passed to the model, which accepts or rejects it; a failed task is not charged either way.

Pricing dimensions

Check the pricing page for current rates. Seedance 2.5 bills video tokens, the official unit:

video tokens = (output seconds + reference video seconds) × width × height × 24 / 1024

The rate per million tokens depends on the output resolution and on whether the request includes a reference video; a request with a reference video uses a lower rate for all of its tokens. Text, image and audio inputs are not billed. At 16:9, one second is 9,607.5 tokens at 480p (854×480), 21,600 at 720p, 48,600 at 1080p.

Requests with reference videos also have a minimum token threshold. For estimates, use at least ceil(output seconds × 2 / 3) reference seconds in the formula, even when the original reference videos are shorter. This applies to both draft and final tasks; the draft clip itself does not become a reference video. Actual charges follow the completed task's reported usage.

The charge follows the tokens the finished video reports (output.usage.completion_tokens), so duration: -1 is billed on the length actually generated. Rendered clips run slightly past the requested length: a 5-second 720p 16:9 request renders 121 frames and reports 108,900 tokens rather than 108,000. View final charges in Task logs. Failed tasks are not charged.

Output schema

Submission returns the new task:

{"id": "task_...", "model": "dreamina-seedance-2-5", "status": "processing", "created_at": 1790321515}

Get the task

curl https://api.toklab.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $TOKLAB_API_KEY"

Poll every 10–20 seconds until status is completed or failed. A network timeout while polling does not mean generation failed: keep the task ID and resume checking it. Do not create another task to check progress.

Complete polling example

Run this after the Python submission example above.

import time

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.toklab.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['TOKLAB_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        print(task["output"]["video_url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Completed task

{
  "id": "task_...",
  "model": "dreamina-seedance-2-5",
  "status": "completed",
  "created_at": 1790321515,
  "finished_at": 1790321652,
  "output": {
    "video_url": "https://static.toklab.ai/media/tasks/task_example/0.mp4",
    "last_frame_url": "https://static.toklab.ai/media/tasks/task_example/last_frame/0.jpg",
    "content": {
      "video_url": "https://static.toklab.ai/media/tasks/task_example/0.mp4",
      "last_frame_url": "https://static.toklab.ai/media/tasks/task_example/last_frame/0.jpg"
    },
    "usage": {"completion_tokens": 108900, "total_tokens": 108900},
    "seed": 42,
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "framespersecond": 24,
    "generate_audio": true,
    "draft": false,
    "output_format": "mp4",
    "service_tier": "default",
    "execution_expires_after": 172800,
    "priority": 0
  }
}

Video URLs are hosted on our storage. Save the file to your own storage when you need a durable copy.

Errors

Requests rejected before a task is created return an HTTP error with an error object and are not charged. A task that fails after acceptance returns HTTP 200 when queried, with status: "failed" and an error object. Output withheld by content filtering fails with content_policy_violation; a task that runs past execution_expires_after fails with task_expired.

See the shared error catalog for codes, HTTP statuses, and retry guidance.

{
  "id": "task_...",
  "model": "dreamina-seedance-2-5",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

If submission itself times out, check Task logs before submitting again: the first request may have been accepted.

Tips

• Describe the subject, the action, the camera move, and the lighting in full sentences.
• Draft at 480p with a short duration, then render the keeper at a higher resolution.
• Chain shots with return_last_frame: use the returned frame as the next task's first_frame.
• To edit footage, set omni_reference_task_type to edit and describe only what should change.

Related

• Seedance 2.5 pricing
• Download OpenAPI
• Copyable Markdown

Draft preview and final video

Set draft: true to generate a 480p preview. Other resolutions are invalid in draft mode. Preview generation uses the same token usage and unit price as standard 480p generation.

{
  "model": "dreamina-seedance-2-5",
  "content": [{ "type": "text", "text": "A fox walks through a sunny garden." }],
  "draft": true,
  "resolution": "480p",
  "duration": 4,
  "ratio": "16:9"
}

Poll the returned TokLab task ID until status is completed and output.draft is true. Within 7 days of the draft's creation, submit a separate request using that ID:

{
  "model": "dreamina-seedance-2-5",
  "content": [{ "type": "draft_task", "draft_task": { "id": "task_YOUR_DRAFT_ID" } }],
  "resolution": "1080p"
}

The draft must belong to your account, have completed, and use the same model. content must contain only one draft_task item. Explicitly set resolution to 1080p; omit draft or set it to false. Do not send duration, ratio, seed, generate_audio, omni_reference_task_type, text, or media again, even with the same values. These settings are inherited from the draft.

You may set watermark, return_last_frame, output_format, execution_expires_after, priority, safety_identifier, and service_tier: "default" for the new task. Omitted output options use their defaults. content_filter is inherited and cannot be changed. A successful final video returns a new task ID, output.draft: false, and output.draft_task_id containing your original TokLab draft ID. One draft can be used for multiple separate final generations before it expires.

Draft and final video are billed independently. The final video uses the 1080p rate for the original draft's input category: if the draft used reference video, the final also uses the reference-video rate and includes the original reference video's duration in token usage. The draft clip itself is not added as an input video. Each task uses the price in effect when it is submitted. Failed requests are not charged.