Capabilities

Seedance 2.5

bytedance/seedance-2.5 makes video from a prompt, frames or references, with optional generated speech and sound. It is a job on POST /api/v1/videos.

Seedance 2.5 is a video generation model for clips of 4 to 30 seconds at 720P or 1080P. It works from a text prompt alone, from a first frame or a first and last frame, or from reference images, videos and audio clips. With generate_audio: true it also makes speech, sound effects and music. The rules every video job follows are on the Video generation page.

Night-market vendor, with speech and sound: 720P, 8 seconds, 16:9, with generated speech and sound. AI Hub 2026-11-07. Compressed display copy; its prompt and request are under Examples.

Capabilities and limits

These values are the bytedance/seedance-2.5 row of the model tables on the Video generation page, which draws them from the same data. They carry no prices: the price of a request depends on its inputs, as Pricing shows.

PropertyValue
Seconds4 to 30
Resolutions720P, 1080P
Ratios16:9, 9:16, 1:1, 4:3, 3:4, 21:9; adaptive with a first frame
Prompt charactersUp to 20,000
Text to videoYes
First frameYes
First and last frameYes
Reference imagesUp to 30
Reference videosUp to 10
Reference audioUp to 10
generate_audioSwitch, default off
seed, watermark, negative_promptNo
  • Frames and references are not sent together. last_frame needs a first_frame.
  • Ratio adaptive is accepted with a first frame, where the output follows the frame. With a first and last frame, send adaptive or leave aspect_ratio out.
  • generate_audio is off by default. With true, put words to be spoken in quotation marks in the prompt and describe the sounds you want.

Inputs and output

  • Frames: a public https URL (at most 2,048 characters, with no port, credentials or fragment, and not an IP address) or a base64 PNG, JPEG or WebP data: image. A PNG or JPEG uploaded through /v1/files can be named as tokenhub://files/<id>.
  • Reference images: 1 to 30, as for frames; each 300 to 6,000 px on a side, with a width to height ratio from 0.4 to 2.5, and under 30 MB.
  • Reference videos: 1 to 10, a public https URL only (a data: video is refused); MP4 or MOV, 24 to 60 FPS, under 200 MB, each 2 to 30 seconds and 30 seconds in all.
  • Reference audio: 1 to 10 WAV or MP3 clips, each 2 to 30 seconds and 30 seconds in all, each under 15 MB. Audio can be the only reference.
  • In the prompt, name references as Image 1, Video 1 and Audio 1, in the order sent.
  • Output: one MP4, with an audio track when generate_audio is true. The result can be downloaded for 24 hours after the job completes, until content_expires_at (the completion time plus 24 hours). Download it before then.

Pricing

Price basis: Output tokens, by resolution; a reference video uses its own rows. The model publishes its prices as tables in tokenhub_price_table, on the model and on each entry of endpoints; GET /api/v1/videos/models returns them without a key. A request is priced by the table of the upstream provider that serves it, and the inputs of the request decide which one does, so there is one table for each case below. Each row is one case, named by the output resolution and by whether the request has a reference video, and gives the USD amount for a number of output tokens. The row that matches your request prices it. The Models page shows the same prices.

Requests without video assets

CasePriceList price
480P and 720P, no video inputUSD 10.7 per million output tokensNot listed
480P and 720P, with video inputUSD 6.4 per million output tokensNot listed
1080P, no video inputUSD 11.7 per million output tokensNot listed
1080P, with video inputUSD 7 per million output tokensNot listed

Requests that use video assets

CasePriceList price
480P and 720P, no video inputUSD 8.82 per million output tokensUSD 9.8 per million output tokens
480P and 720P, with video inputUSD 5.292 per million output tokensUSD 5.88 per million output tokens
1080P, no video inputUSD 9.702 per million output tokensUSD 10.78 per million output tokens
1080P, with video inputUSD 5.796 per million output tokensUSD 6.44 per million output tokens

Reference images and audio add no charge of their own, and in each table a video asset counts as a reference video. A completed job's usage carries its cost in USD.

Seedance 2.5 Flash

Available from 15 November 2026, 14:00 SGT (06:00 UTC). Until then a request for it is refused.

bytedance/seedance-2.5-flash is the faster, lower-priced Seedance 2.5 model, for clips at 480P or 720P. Its provider states it is about twice as fast as Seedance 2.5 and about 34% cheaper. It takes the same request fields, with lower reference limits and no 1080P. Both models are listed in the tables on the Video generation page.

Propertybytedance/seedance-2.5bytedance/seedance-2.5-flash
Seconds4 to 304 to 30, 5 by default
Resolutions720P, 1080P480P, 720P
Ratios16:9, 9:16, 1:1, 4:3, 3:4, 21:9; adaptive with a first frame16:9, 9:16, 1:1, 4:3, 3:4, 21:9; adaptive with a first frame
First frame, and first and last frameYesYes, up to 2 frame images
Reference imagesUp to 30Up to 10
Reference videosUp to 10Up to 5, 30 seconds in all
Reference audioUp to 10Up to 5, 30 seconds in all; can be the only reference
Video assets (asset://)YesNo
  • Price basis: Output tokens, by resolution; a reference video uses its own rows, from the model's own tokenhub_price_table, with one row for requests without a reference video and one for requests with one. The amounts are on the Models page and in the Seedance notes of Video generation. Output tokens are width × height × frames / 1,024: a 4-second 720P clip is about 86,400 tokens, a 4-second 480P clip about 38,830.
  • An asset:// reference is refused with asset_route_unavailable: send images, videos and audio inline as https URLs, or images as base64 data: URIs.
  • return_last_frame: true asks for the clip's last frame as an image. The completed job then carries last_frame_url, and GET /api/v1/videos/{job_id}/last-frame serves it for as long as the video can be downloaded.
  • Prompts are accepted up to 20,000 characters, and generate_audio works as on Seedance 2.5.

Quickstart

Submit, poll, download. Set the key once; the examples read it and an Idempotency-Key from the environment.

bash
export TOKENHUB_API_KEY="sk-tokenhub-…"
export TOKENHUB_IDEMPOTENCY_KEY="$(uuidgen)"

1. Submit a job

A new job answers 202 with its id and where to poll it. Sending the same Idempotency-Key again within 24 hours returns the same job and never starts a second one.

import json
import os
import urllib.request

body = {
  "model": "bytedance/seedance-2.5",
  "prompt": "A Gen Z street dancer in a holographic jacket lands a slow-motion backflip on a rain-soaked rooftop at night, neon signs reflecting in the puddles, fireworks bursting over the skyline behind her, handheld cinematic camera, no text.",
  "duration": 4,
  "resolution": "720P",
  "aspect_ratio": "16:9"
}
request = urllib.request.Request(
    "https://tokenhub-api.belive.sg/api/v1/videos",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['TOKENHUB_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": os.environ["TOKENHUB_IDEMPOTENCY_KEY"],
    },
)
with urllib.request.urlopen(request, timeout=30) as response:
    job = json.load(response)
print(job["id"], job["polling_url"])
json
{
  "id": "job_…",
  "generation_id": "req_…",
  "polling_url": "https://tokenhub-api.belive.sg/api/v1/videos/job_…",
  "status": "pending"
}

2. Poll the job

Set TOKENHUB_VIDEO_JOB_ID to the returned id. status moves from pending and in_progress to completed, failed, cancelled or expired. The Video generation page has the details.

import json
import os
import time
import urllib.request

job_id = os.environ["TOKENHUB_VIDEO_JOB_ID"]
url = "https://tokenhub-api.belive.sg/api/v1/videos/" + job_id
headers = {"Authorization": f"Bearer {os.environ['TOKENHUB_API_KEY']}"}
for attempt in range(120):
    request = urllib.request.Request(url, headers=headers)
    with urllib.request.urlopen(request, timeout=30) as response:
        job = json.load(response)
    print(job["status"])
    if job["status"] not in ("pending", "in_progress"):
        break
    time.sleep(3)
else:
    raise TimeoutError("Job is still running; poll it again later")
print(json.dumps(job, indent=2))

3. Download the video

Download before content_expires_at. These are server-side examples; do not forward your AI Hub key to a download URL on another host.

import os
import shutil
import urllib.error
import urllib.request

job_id = os.environ["TOKENHUB_VIDEO_JOB_ID"]
request = urllib.request.Request(
    "https://tokenhub-api.belive.sg/api/v1/videos/" + job_id + "/content",
    headers={"Authorization": f"Bearer {os.environ['TOKENHUB_API_KEY']}"},
)
class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=60)
except urllib.error.HTTPError as response:
    if response.code != 302:
        raise
    download_url = response.headers.get("Location")
    if not download_url:
        raise RuntimeError("Missing redirect Location")
    response.close()
    # This request goes to the CDN without the AI Hub Authorization header.
    response = urllib.request.urlopen(download_url, timeout=120)
with response, open("video.mp4", "wb") as output:
    shutil.copyfileobj(response, output)

Examples

These five clips were generated through AI Hub production on 2026-11-07 with bytedance/seedance-2.5. They cover a reference video, a first frame, 1080P and generated speech and sound; each shows its prompt. The videos are compressed display copies; each new generation produces a different result. Each Request block is the body that made the clip, sent as in the quickstart.

Pop idol, from a reference video

bytedance/seedance-2.5

Requested: 720P · 4s · 16:9 · generate_audio: false

Input: Text and a reference video

Prompt: A pop idol in a crystal-studded stage outfit performs the dance from video 1 on a spinning LED stage, lasers sweeping and flame jets firing on every beat, a sea of glowing lightsticks in the crowd, no text.

AI Hub 2026-11-07. Original output 1280 × 720, 4 seconds, without audio. Preview 640 × 360, compressed for the docs page.
Request
const body = {
  "prompt": "A pop idol in a crystal-studded stage outfit performs the dance from video 1 on a spinning LED stage, lasers sweeping and flame jets firing on every beat, a sea of glowing lightsticks in the crowd, no text.",
  "duration": 4,
  "resolution": "720P",
  "model": "bytedance/seedance-2.5",
  "aspect_ratio": "16:9",
  "input_references": [
    {
      "type": "video_url",
      "video_url": {
        "url": "https://belivesdk-clients.belive.sg/tokenhub/qa/samples/tencent-wave1-2026-10-18/motion-reference-dance2.mp4"
      }
    }
  ],
  "generate_audio": false
};
const response = await fetch("https://tokenhub-api.belive.sg/api/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.TOKENHUB_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": process.env.TOKENHUB_IDEMPOTENCY_KEY,
  },
  body: JSON.stringify(body),
});
if (!response.ok) throw new Error("Video submit failed: " + response.status);
const job = await response.json();
console.log(job.id, job.polling_url);

Runway, 1080P

bytedance/seedance-2.5

Requested: 1080P · 4s · 16:9 · generate_audio: false

Input: Text only

Prompt: A runway model in a mirror-sequin gown strides through falling gold confetti at a night-time fashion show, camera flashes strobing from the crowd, her braids swinging in slow motion, sparks cascading from the ceiling, no text, no logos.

AI Hub 2026-11-07. Original output 1920 × 1080, 4 seconds, without audio. Preview 640 × 360, compressed for the docs page.
Request
const body = {
  "prompt": "A runway model in a mirror-sequin gown strides through falling gold confetti at a night-time fashion show, camera flashes strobing from the crowd, her braids swinging in slow motion, sparks cascading from the ceiling, no text, no logos.",
  "duration": 4,
  "resolution": "1080P",
  "model": "bytedance/seedance-2.5",
  "aspect_ratio": "16:9",
  "generate_audio": false
};
const response = await fetch("https://tokenhub-api.belive.sg/api/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.TOKENHUB_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": process.env.TOKENHUB_IDEMPOTENCY_KEY,
  },
  body: JSON.stringify(body),
});
if (!response.ok) throw new Error("Video submit failed: " + response.status);
const job = await response.json();
console.log(job.id, job.polling_url);

Rooftop backflip

bytedance/seedance-2.5

Requested: 720P · 4s · 16:9 · generate_audio: false

Input: Text only

Prompt: A Gen Z street dancer in a holographic jacket lands a slow-motion backflip on a rain-soaked rooftop at night, neon signs reflecting in the puddles, fireworks bursting over the skyline behind her, handheld cinematic camera, no text.

AI Hub 2026-11-07. Original output 1280 × 720, 4 seconds, without audio. Preview 640 × 360, compressed for the docs page.
Request
const body = {
  "prompt": "A Gen Z street dancer in a holographic jacket lands a slow-motion backflip on a rain-soaked rooftop at night, neon signs reflecting in the puddles, fireworks bursting over the skyline behind her, handheld cinematic camera, no text.",
  "duration": 4,
  "resolution": "720P",
  "model": "bytedance/seedance-2.5",
  "aspect_ratio": "16:9",
  "generate_audio": false
};
const response = await fetch("https://tokenhub-api.belive.sg/api/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.TOKENHUB_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": process.env.TOKENHUB_IDEMPOTENCY_KEY,
  },
  body: JSON.stringify(body),
});
if (!response.ok) throw new Error("Video submit failed: " + response.status);
const job = await response.json();
console.log(job.id, job.polling_url);

Friends and a firework, from a first frame

bytedance/seedance-2.5

Requested: 720P · 4s · adaptive · generate_audio: false

Input: Text and a first frame (a plain colour gradient, 640 × 360)

Prompt: From this opening frame, a crew of friends in glowing streetwear bursts into the shot and leaps together as a giant firework blooms overhead, colored smoke swirling around them, slow motion, no text.

AI Hub 2026-11-07. Original output 1280 × 720, 4 seconds, without audio. Preview 640 × 360, compressed for the docs page.
Request
const body = {
  "prompt": "From this opening frame, a crew of friends in glowing streetwear bursts into the shot and leaps together as a giant firework blooms overhead, colored smoke swirling around them, slow motion, no text.",
  "duration": 4,
  "resolution": "720P",
  "model": "bytedance/seedance-2.5",
  "aspect_ratio": "adaptive",
  "frame_images": [
    {
      "type": "image_url",
      "image_url": {
        "url": "data:image/png;base64,iVBORw0KGgo…"
      },
      "frame_type": "first_frame"
    }
  ],
  "generate_audio": false
};
const response = await fetch("https://tokenhub-api.belive.sg/api/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.TOKENHUB_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": process.env.TOKENHUB_IDEMPOTENCY_KEY,
  },
  body: JSON.stringify(body),
});
if (!response.ok) throw new Error("Video submit failed: " + response.status);
const job = await response.json();
console.log(job.id, job.polling_url);

Night-market vendor, with speech and sound

bytedance/seedance-2.5

Requested: 720P · 8s · 16:9 · generate_audio: true

Input: Text only

Prompt: At a busy night market, a cheerful young street-food vendor in a red apron flips sizzling skewers over a flaming grill and calls out to the camera, "Fresh off the fire, come and try!", crowd chatter and upbeat music in the background, oil crackling, warm lantern light, handheld cinematic camera, no text.

AI Hub 2026-11-07. Original output 1280 × 720, 8 seconds, with generated speech and sound. Preview 640 × 360, compressed for the docs page.
Request
const body = {
  "prompt": "At a busy night market, a cheerful young street-food vendor in a red apron flips sizzling skewers over a flaming grill and calls out to the camera, \"Fresh off the fire, come and try!\", crowd chatter and upbeat music in the background, oil crackling, warm lantern light, handheld cinematic camera, no text.",
  "duration": 8,
  "resolution": "720P",
  "model": "bytedance/seedance-2.5",
  "aspect_ratio": "16:9",
  "generate_audio": true
};
const response = await fetch("https://tokenhub-api.belive.sg/api/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.TOKENHUB_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": process.env.TOKENHUB_IDEMPOTENCY_KEY,
  },
  body: JSON.stringify(body),
});
if (!response.ok) throw new Error("Video submit failed: " + response.status);
const job = await response.json();
console.log(job.id, job.polling_url);

Video assets (AIGC)

A video asset, also called AIGC (AI-generated content), is an image, a video or an audio file of yours, saved once in a workspace and then used in any number of Seedance 2.5 requests. It is meant for virtual and fictional characters, and for other material you have the right to use. An asset is named in a request as asset://<id>, so the file itself is never sent again.

  • POST /api/v1/videos/assets takes type (image, video or audio), url (a public https URL, at most 2,048 characters; a data: upload is refused), an optional name (1 to 64 characters, the asset's id by default) and consent, which must be {"confirmed": true}. Without it the answer is 400 invalid_request and nothing is stored. It answers 202 with the asset in processing.
  • Creation is asynchronous. status goes from processing to ready, or to failed with an error object (the URL could not be read, the file was refused, or processing took too long). Poll GET /api/v1/videos/assets/{id} until it is not processing.
  • GET /api/v1/videos/assets lists the workspace's assets, newest first, as {"items": […], "next_cursor": …} (limit 1 to 100, default 50; cursor). Failed assets are listed; deleted ones are not. DELETE /api/v1/videos/assets/{id} answers 204, and again 204 if repeated. The same operations are served under /v1.
  • An asset has id (asset_ and 26 characters), object: "video.asset", type, name, status, error (null unless failed) and created_at. The media itself is never returned.

Use an asset in a video request

Put the asset in input_references as the url of the item whose type matches the asset: image_url for an image, video_url for a video, audio_url for an audio file. An image asset can also be a frame_images item. In the prompt, refer to them as Image 1, Video 1 and Audio 1, numbered in the order sent.

json
{
  "model": "bytedance/seedance-2.5",
  "prompt": "The dress from Image 1 …",
  "input_references": [
    { "type": "image_url", "image_url": { "url": "asset://asset_…" } },
    { "type": "video_url", "video_url": { "url": "asset://asset_…" } },
    { "type": "audio_url", "audio_url": { "url": "asset://asset_…" } }
  ]
}

Rules

  • An asset belongs to the workspace of the key that created it. Another workspace's id answers 404, the same as an id that does not exist. A workspace holds at most 1,000 assets that are processing or ready.
  • An asset is stored with one upstream provider, so a request that uses one is served by that provider only. A provider preference or a workspace model pin that excludes it is refused with asset_provider_excluded. Assets work on bytedance/seedance-2.5 while that provider serves the model.
  • The provider refuses the face of a real person. Use virtual or fictional characters. A refused file leaves the asset failed.
  • Consent is required on every creation. You attest that you have the right to use the people and material shown; the attestation is recorded with the account and the key.
  • Creating, listing, keeping and deleting assets cost nothing. The generation is priced by the video assets table under Pricing, where a video asset counts as a reference video, as a reference video at an https URL does. Image and audio assets add nothing.

Asset errors

Each answer has the usual error.type; the code that tells these cases apart is error.metadata.reason. Using an asset is checked before a job is started, so each of these costs nothing.

Statustype and metadata.reasonWhen
404not_found, asset_not_foundThe id is unknown, deleted or another workspace's.
409conflict, asset_not_readyThe asset is still processing or failed. Poll it, then send the request again.
400invalid_request, asset_type_mismatchThe item's type differs from the asset's, for example an image asset in a video_url item.
400invalid_request, asset_provider_excludedA provider preference or a workspace pin of the model leaves out the upstream provider that stores assets.
400invalid_request, asset_route_unavailableNo upstream provider that stores assets serves the model.
409conflict, asset_limitCreation with 1,000 assets already held; the answer carries metadata.limit. Delete one first.

Example: save, wait, use, delete

The steps with curl. The video request is the Submit a job request, so it needs an Idempotency-Key and is polled and downloaded as above.

bash
export TOKENHUB_API_KEY="sk-tokenhub-…"
AUTH="Authorization: Bearer $TOKENHUB_API_KEY"

# 1. Save the image once. 202, status "processing".
ASSET_ID=$(curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos/assets' \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "url": "https://example.com/tropical-dress.jpg",
    "name": "tropical-dress",
    "consent": { "confirmed": true }
  }' | jq -r .id)

# 2. Poll until status is "ready" ("failed" carries an error).
until [ "$(curl -sS "https://tokenhub-api.belive.sg/api/v1/videos/assets/$ASSET_ID" -H "$AUTH" | jq -r .status)" != "processing" ]; do
  sleep 3
done

# 3. Use it in a Seedance 2.5 request. Image 1 in the prompt is the asset.
curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos' \
  -H "$AUTH" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @- <<EOF
{
  "model": "bytedance/seedance-2.5",
  "duration": 4,
  "resolution": "720P",
  "aspect_ratio": "9:16",
  "generate_audio": true,
  "prompt": "A young woman wearing the tropical dress from Image 1 spins at a rooftop garden party at dusk, string lights glowing, friends cheering, confetti in the air, she laughs and says \"Best night ever!\", slow motion, no text.",
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://$ASSET_ID"
      }
    }
  ]
}
EOF

# 4. Delete the asset when you no longer need it. 204, no body.
curl --fail-with-body -sS -X DELETE "https://tokenhub-api.belive.sg/api/v1/videos/assets/$ASSET_ID" -H "$AUTH"

An image asset in a video, with audio

bytedance/seedance-2.5

Requested: 720P · 4s · 9:16 · generate_audio: true

Input: One image asset, an image of a tropical dress

Prompt: A young woman wearing the tropical dress from Image 1 spins at a rooftop garden party at dusk, string lights glowing, friends cheering, confetti in the air, she laughs and says "Best night ever!", slow motion, no text.

AI Hub 2026-11-07. Original output 720 × 1280, 4 seconds, with generated speech and sound. Preview 360 × 640, compressed for the docs page.

Draft mode

Draft mode makes a 480P preview first and the 1080P video from it only when the preview is right. It works on bytedance/seedance-2.5 only: bytedance/seedance-2.5-flash has no Draft mode, and a request for it with draft or draft_job_id is refused with 400 unsupported_parameter.

1. Make the Draft

Send an ordinary request with draft: true and resolution: "480P". A Draft takes the prompt, frames and references of any other Seedance 2.5 request, including a reference image, video or audio. The job answers 202 as usual, and the job object carries draft: true. A Draft with any other resolution is 400 invalid_request.

json
{
  "model": "bytedance/seedance-2.5",
  "prompt": "A cat walks along a rooftop ledge at sunrise, slow tracking shot, soft wind, no text.",
  "duration": 4,
  "resolution": "480P",
  "aspect_ratio": "16:9",
  "draft": true,
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/cat.jpg"
      }
    }
  ]
}

2. Make the final

Poll the Draft until it is completed and look at its video. Then send the Draft's job id as draft_job_id with resolution: "1080P". The request carries the model, the id and the resolution, and nothing else of the video. The final is a new job with its own id; its job object carries draft_job_id and draft: false.

json
{
  "model": "bytedance/seedance-2.5",
  "draft_job_id": "job_…",
  "resolution": "1080P"
}

The whole flow with curl:

bash
export TOKENHUB_API_KEY="sk-tokenhub-…"
AUTH="Authorization: Bearer $TOKENHUB_API_KEY"

# 1. Make the Draft: 480P, draft true. 202, with "draft": true.
DRAFT_JOB_ID=$(curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos' \
  -H "$AUTH" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @- <<EOF | jq -r .id
{
  "model": "bytedance/seedance-2.5",
  "prompt": "A cat walks along a rooftop ledge at sunrise, slow tracking shot, soft wind, no text.",
  "duration": 4,
  "resolution": "480P",
  "aspect_ratio": "16:9",
  "draft": true,
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/cat.jpg"
      }
    }
  ]
}
EOF
)

# 2. Poll the Draft until its status is "completed", and look at its video.
curl -sS "https://tokenhub-api.belive.sg/api/v1/videos/$DRAFT_JOB_ID" -H "$AUTH" | jq '{status, draft}'

# 3. Make the final from the Draft's id: the model, the id and the resolution only.
curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos' \
  -H "$AUTH" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @- <<EOF
{
  "model": "bytedance/seedance-2.5",
  "draft_job_id": "$DRAFT_JOB_ID",
  "resolution": "1080P"
}
EOF

Rules

  • What the final reuses. The final takes the Draft's prompt, references, frames, seed, duration, ratio and generate_audio. It matches the Draft's composition, subject and lighting, and is generated again at 1080P.
  • What the final refuses. With draft_job_id, only model, resolution (1080P), return_last_frame, watermark: false, provider and the Idempotency-Key header are accepted. A prompt, negative_prompt, frame or reference input, duration, aspect_ratio, seed, watermark: true or generate_audio is 400 unsupported_parameter, and the message names the field. To change any of them, make a new Draft. draft and draft_job_id in one request is 400.
  • Which Draft. A completed Draft job of bytedance/seedance-2.5 in the same workspace as the key.
  • Validity. A Draft can start a final for 14 days after it was created. After that the answer is 409, draft_job_expired.
  • One provider. Drafts and finals are served by one upstream provider only, with no fallback to another provider, and a final runs on the credential that made its Draft. A provider preference or a workspace model pin that leaves that provider out is 400 invalid_request with draft_provider_excluded, for the Draft and for the final. If that provider or credential cannot serve the final when you send it, the answer is 409, draft_job_route_unavailable. A final is not queued: if that provider is at capacity, the answer is 429 and you send the final again later.
  • Output. The Draft is an H.264 MP4 at 480P. The final is an H.265 (HEVC) MP4 at 1080P. Check that the players and editors you use open H.265.
  • Pricing. The Draft and the final are two jobs, each priced and costed on its own: the Draft as a 480P request, the final as a 1080P request. The rows are in the tables under Pricing and in tokenhub_price_table. If the Draft had a reference video, the final is priced on the 1080P with-video-input row, and it counts the seconds of that reference video as well as the seconds of output, so it has more tokens than a final with no reference video. A completed job's usage carries the cost of that job. A Draft that is never used for a final costs only the Draft.

Draft errors

These are checked before a job is started, so each costs nothing. The code that tells the cases apart is error.metadata.reason.

Statustype and metadata.reasonWhen
400unsupported_parameterdraft or draft_job_id on a model without Draft mode, such as bytedance/seedance-2.5-flash, or a field a final refuses. The message names the field.
400invalid_requestdraft: true with a resolution other than 480P, a final with a resolution other than 1080P, or draft and draft_job_id together.
400invalid_request, draft_provider_excludedA provider preference or a workspace pin leaves out the upstream provider that serves Draft mode, for a Draft or a final.
404not_found, job_not_foundThe draft_job_id is unknown or belongs to another workspace; the answer is the same for both.
409conflict, draft_job_not_readyThe Draft is not completed yet: poll it, then send the final again. If the Draft failed or was cancelled, the message says so: make a new Draft.
409conflict, draft_job_expiredThe Draft is more than 14 days old. Make a new Draft.
409conflict, draft_job_not_draftThe job named is not a Draft.
409conflict, draft_job_route_unavailableThe Draft's provider or credential cannot serve the final now, or the Draft is of another model.
409conflict, previous_job_key_changedThe workspace's own provider key (BYOK) changed since the Draft was made.

Errors

Limits are applied before anything is started, so each of these costs nothing and starts no job. See Errors and recovery for the envelope and the retry rules.

Status and typeWhen
400
unsupported_parameter
seed, watermark or negative_prompt, which this model does not take, or size, which is not a video field.
400
invalid_request
A value outside a limit above: duration not 4 to 30, resolution other than 720P or 1080P, a ratio not listed, a prompt over 20,000 characters, or more than 30 images, 10 videos or 10 audio clips. The message names the field and the range.
400
invalid_request
frame_images and input_references together, a last_frame with no first_frame, or an input that is not a public https URL or a base64 image.
400, 404, 409
see Draft errors
draft or draft_job_id used wrongly, or a Draft that is unknown, not ready, expired or not servable: Draft mode.
400, 404, 409
see Asset errors
An asset id that is unknown, not ready, of another type, or stored with a provider the request excludes: Video assets (AIGC).
409
conflict
The same Idempotency-Key with a different body.
429
rate_limit_exceeded
The organisation is at its concurrent video job limit: queued and executing jobs both count, and the default is 10. See Rate limits & caps. Honour Retry-After when present.

A job that waits ten minutes without starting ends with status: failed and queue_expired: true, and is not costed. After a timeout or a 5xx the job may have started: resend with the same Idempotency-Key instead of a new one.