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.
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.
| Property | Value |
|---|---|
| Seconds | 4 to 30 |
| Resolutions | 720P, 1080P |
| Ratios | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9; adaptive with a first frame |
| Prompt characters | Up to 20,000 |
| Text to video | Yes |
| First frame | Yes |
| First and last frame | Yes |
| Reference images | Up to 30 |
| Reference videos | Up to 10 |
| Reference audio | Up to 10 |
generate_audio | Switch, default off |
seed, watermark, negative_prompt | No |
- Frames and references are not sent together.
last_frameneeds afirst_frame. - Ratio
adaptiveis accepted with a first frame, where the output follows the frame. With a first and last frame, sendadaptiveor leaveaspect_ratioout. generate_audiois off by default. Withtrue, 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/filescan be named astokenhub://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_audioistrue. The result can be downloaded for 24 hours after the job completes, untilcontent_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
| Case | Price | List price |
|---|---|---|
| 480P and 720P, no video input | USD 10.7 per million output tokens | Not listed |
| 480P and 720P, with video input | USD 6.4 per million output tokens | Not listed |
| 1080P, no video input | USD 11.7 per million output tokens | Not listed |
| 1080P, with video input | USD 7 per million output tokens | Not listed |
Requests that use video assets
| Case | Price | List price |
|---|---|---|
| 480P and 720P, no video input | USD 8.82 per million output tokens | USD 9.8 per million output tokens |
| 480P and 720P, with video input | USD 5.292 per million output tokens | USD 5.88 per million output tokens |
| 1080P, no video input | USD 9.702 per million output tokens | USD 10.78 per million output tokens |
| 1080P, with video input | USD 5.796 per million output tokens | USD 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.
| Property | bytedance/seedance-2.5 | bytedance/seedance-2.5-flash |
|---|---|---|
| Seconds | 4 to 30 | 4 to 30, 5 by default |
| Resolutions | 720P, 1080P | 480P, 720P |
| Ratios | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9; adaptive with a first frame | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9; adaptive with a first frame |
| First frame, and first and last frame | Yes | Yes, up to 2 frame images |
| Reference images | Up to 30 | Up to 10 |
| Reference videos | Up to 10 | Up to 5, 30 seconds in all |
| Reference audio | Up to 10 | Up to 5, 30 seconds in all; can be the only reference |
Video assets (asset://) | Yes | No |
- 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 withasset_route_unavailable: send images, videos and audio inline as https URLs, or images as base64data:URIs. return_last_frame: trueasks for the clip's last frame as an image. The completed job then carrieslast_frame_url, andGET /api/v1/videos/{job_id}/last-frameserves it for as long as the video can be downloaded.- Prompts are accepted up to 20,000 characters, and
generate_audioworks as on Seedance 2.5.
Quickstart
Submit, poll, download. Set the key once; the examples read it and an Idempotency-Key from the environment.
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"])
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({ "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" }), }); if (!response.ok) throw new Error("Video submit failed: " + response.status); const job = await response.json(); console.log(job.id, job.polling_url);
curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos' \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $TOKENHUB_IDEMPOTENCY_KEY" \ -d '{ "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" }'
{ "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))
const jobId = process.env.TOKENHUB_VIDEO_JOB_ID; let job; for (let attempt = 0; attempt < 120; attempt++) { const response = await fetch("https://tokenhub-api.belive.sg/api/v1/videos/" + encodeURIComponent(jobId), { headers: { Authorization: "Bearer " + process.env.TOKENHUB_API_KEY }, }); if (!response.ok) throw new Error("Video poll failed: " + response.status); job = await response.json(); console.log(job.status); if (job.status !== "pending" && job.status !== "in_progress") break; if (attempt === 119) throw new Error("Job is still running; poll it again later"); await new Promise((resolve) => setTimeout(resolve, 3000)); } console.log(job);
curl --fail-with-body -sS "https://tokenhub-api.belive.sg/api/v1/videos/$TOKENHUB_VIDEO_JOB_ID" \ -H "Authorization: Bearer $TOKENHUB_API_KEY"
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)
import { writeFile } from "node:fs/promises"; const jobId = process.env.TOKENHUB_VIDEO_JOB_ID; const response = await fetch( "https://tokenhub-api.belive.sg/api/v1/videos/" + encodeURIComponent(jobId) + "/content", { headers: { Authorization: "Bearer " + process.env.TOKENHUB_API_KEY }, redirect: "manual", }, ); let video = response; if (response.status === 302) { const location = response.headers.get("location"); if (!location) throw new Error("Missing redirect Location"); // Fetch the CDN URL without the AI Hub Authorization header. video = await fetch(location); } if (!video.ok) throw new Error("Video download failed: " + video.status); await writeFile("video.mp4", Buffer.from(await video.arrayBuffer()));
curl --fail-with-body -sS -L --proto-redir '=https' \ "https://tokenhub-api.belive.sg/api/v1/videos/$TOKENHUB_VIDEO_JOB_ID/content" \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -o video.mp4
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.5Requested: 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.
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);
curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos' \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $TOKENHUB_IDEMPOTENCY_KEY" \ -d '{ "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 }'
Runway, 1080P
bytedance/seedance-2.5Requested: 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.
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);
curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos' \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $TOKENHUB_IDEMPOTENCY_KEY" \ -d '{ "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 }'
Rooftop backflip
bytedance/seedance-2.5Requested: 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.
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);
curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos' \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $TOKENHUB_IDEMPOTENCY_KEY" \ -d '{ "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 }'
Friends and a firework, from a first frame
bytedance/seedance-2.5Requested: 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.
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);
curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos' \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $TOKENHUB_IDEMPOTENCY_KEY" \ -d '{ "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 }'
Night-market vendor, with speech and sound
bytedance/seedance-2.5Requested: 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.
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);
curl --fail-with-body -sS 'https://tokenhub-api.belive.sg/api/v1/videos' \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $TOKENHUB_IDEMPOTENCY_KEY" \ -d '{ "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 }'
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/assetstakestype(image,videooraudio),url(a public https URL, at most 2,048 characters; adata:upload is refused), an optionalname(1 to 64 characters, the asset's id by default) andconsent, which must be{"confirmed": true}. Without it the answer is400 invalid_requestand nothing is stored. It answers202with the asset inprocessing.- Creation is asynchronous.
statusgoes fromprocessingtoready, or tofailedwith anerrorobject (the URL could not be read, the file was refused, or processing took too long). PollGET /api/v1/videos/assets/{id}until it is notprocessing. GET /api/v1/videos/assetslists the workspace's assets, newest first, as{"items": […], "next_cursor": …}(limit1 to 100, default 50;cursor). Failed assets are listed; deleted ones are not.DELETE /api/v1/videos/assets/{id}answers204, and again204if 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) andcreated_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.
{ "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
providerpreference or a workspace model pin that excludes it is refused withasset_provider_excluded. Assets work onbytedance/seedance-2.5while 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.
| Status | type and metadata.reason | When |
|---|---|---|
404 | not_, asset_ | The id is unknown, deleted or another workspace's. |
409 | conflict, asset_ | The asset is still processing or failed. Poll it, then send the request again. |
400 | invalid_, asset_ | The item's type differs from the asset's, for example an image asset in a video_ item. |
400 | invalid_, asset_ | A provider preference or a workspace pin of the model leaves out the upstream provider that stores assets. |
400 | invalid_, asset_ | No upstream provider that stores assets serves the model. |
409 | conflict, asset_ | Creation 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.
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.5Requested: 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.
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.
{ "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.
{ "model": "bytedance/seedance-2.5", "draft_job_id": "job_…", "resolution": "1080P" }
The whole flow with curl:
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 andgenerate_audio. It matches the Draft's composition, subject and lighting, and is generated again at 1080P. - What the final refuses. With
draft_job_id, onlymodel,resolution(1080P),return_last_frame,watermark: false,providerand theIdempotency-Keyheader are accepted. A prompt,negative_prompt, frame or reference input,duration,aspect_ratio,seed,watermark: trueorgenerate_audiois400 unsupported_parameter, and the message names the field. To change any of them, make a new Draft.draftanddraft_job_idin one request is400. - Which Draft. A completed Draft job of
bytedance/seedance-2.5in 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
providerpreference or a workspace model pin that leaves that provider out is400 invalid_requestwithdraft_provider_excluded, for the Draft and for the final. If that provider or credential cannot serve the final when you send it, the answer is409,draft_job_route_unavailable. A final is not queued: if that provider is at capacity, the answer is429and 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'susagecarries 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.
| Status | type and metadata.reason | When |
|---|---|---|
400 | unsupported_ | draft 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. |
400 | invalid_ | draft: true with a resolution other than 480P, a final with a resolution other than 1080P, or draft and draft_job_id together. |
400 | invalid_, draft_ | A provider preference or a workspace pin leaves out the upstream provider that serves Draft mode, for a Draft or a final. |
404 | not_, job_ | The draft_job_id is unknown or belongs to another workspace; the answer is the same for both. |
409 | conflict, draft_ | The 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. |
409 | conflict, draft_ | The Draft is more than 14 days old. Make a new Draft. |
409 | conflict, draft_ | The job named is not a Draft. |
409 | conflict, draft_ | The Draft's provider or credential cannot serve the final now, or the Draft is of another model. |
409 | conflict, previous_ | The 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 type | When |
|---|---|
400unsupported_ | seed, watermark or negative_, which this model does not take, or size, which is not a video field. |
400invalid_ | 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. |
400invalid_ | frame_ and input_ together, a last_ with no first_, or an input that is not a public https URL or a base64 image. |
400, 404, 409see 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, 409see Asset errors | An asset id that is unknown, not ready, of another type, or stored with a provider the request excludes: Video assets (AIGC). |
409conflict | The same Idempotency-Key with a different body. |
429rate_ | 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.