ByteDance
Seedance 2.5
seedance-2.5/reference-to-video
ByteDance Seed's joint audio-video generation model, supporting continuous clips up to 30 seconds and up to 4K, with precise visual control via multimodal references and timestamp-level editing
Try seedance-2.5/reference-to-video
Input
Showcases
View all showcasesOutput
videoPricing
seedance-2.5/reference-to-video per second
| Specifications | Unit Price |
|---|---|
| 480P | $0.1215 |
| 720P | $0.2715 |
| 1080P | $0.680 |
Overview
The reference-to-video pipeline of Seedance 2.5 is designed for video generation tasks that need source materials to constrain visual consistency. Developers submit a prompt along with at least one reference video, and may also attach image and audio references, so the model can reference the materials in the order @image1, @video1, @audio1 and generate a 4- to 30-second clip at 480p to 1080p. It suits advertising, short-drama, and brand content teams that need to lock down the appearance of characters, products, and scenes across serialized creation, and is also suited to narrative segment production that requires synchronized sound effects and dialogue.
Core Highlights
- Multimodal materials jointly constrain the visuals — supports up to 30 images, 10 videos, and 10 audio clips as simultaneous references, used to lock down the appearance of products, characters, and scenes.
- Prompts reference materials in order — in the prompt, refer to reference items as @image1, @video1, @audio1 in sequence, clearly mapping materials to visual goals.
- Controllable duration and aspect ratio — output duration can be set from 4 to 30 seconds or left to the model to decide automatically; aspect ratio supports 16:9, 9:16, 21:9, and adaptive following the source material.
- Synchronized audio and video generation — by default generates dialogue, sound effects, and background audio synchronized with the visuals, and can be disabled for pure visual output.
Capabilities
Generation driven by reference video: input at least one reference video, and the model generates a new segment based on it rather than extending or editing the original; suited to productions that need to reuse existing shot language and visual texture.
Mixed image and video references: up to 30 images and 10 videos can be submitted in combination to separately constrain characters, products, and scenes, reducing appearance drift across serial content.
Audio references and audio generation: can attach up to 10 wav or mp3 audio references (must be submitted together with at least one reference video), and choose whether to generate synchronized dialogue, sound effects, and background sound.
Resolution and output format options: output supports three tiers—480p, 720p, and 1080p—and formats can be mp4 or mov for professional post-production; billing is by output seconds.
Web search to supplement information: web_search can be enabled so the model retrieves time-sensitive information involved in the prompt before generation, suited to content that needs to cite current facts.
Use Cases
- Advertising and brand teams producing product clips — use product images and live-action reference videos to constrain appearance and generate 4- to 30-second ad segments for campaign assets and social media distribution.
- Short-drama teams maintaining character consistency — use character images and existing clips as references to batch-generate continuous shots of the same character for storyboard assembly and later editing.
- Post-production teams previewing shot plans — submit scene reference videos and composition images to quickly obtain preview clips close to final quality, for client approval and pre-shoot communication.
- Content teams producing audio-video synchronized segments — provide voiceover or music references and enable audio generation to produce clips with synchronized dialogue and sound effects, used directly as final output or for further mixing.
Limitations and Selection Advice
A single generation is at most 30 seconds; longer narratives need to be split into multiple segments generated separately and then stitched together. Reference materials have explicit constraints: videos must be 2 to 30 seconds and total no more than 30 seconds, audio total duration likewise no more than 30 seconds, and individual file size and pixel count also have lower and upper bounds; non-compliant materials will fail directly. This pipeline is for reference-guided generation and does not support video editing or extending the original clip; multi-material referencing also means higher prompt-writing and parameter-tuning costs. For lightweight, single-shot needs without consistency requirements, consider the text-to-video pipeline in the same series.
Frequently asked questions
View all FAQs →-
Does Seedance 2.5 image-to-video require both a first and last frame?
No. In endpoint-frame mode, first_frame_url alone extends the source into a complete shot; add last_frame_url when the ending state must be controlled. A last frame cannot be used by itself. You can instead use reference_image_urls or reference_audio_urls as a separate reference mode without endpoint frames.
-
Can first/last frames be mixed with multimodal references in one request?
The current HiAPI Playground treats them as separate input modes: use first/last frames, or use reference_image_urls and reference_audio_urls. Keep one mode to avoid conflicting guidance. Use seedance-2.5/reference-to-video when a reference video must guide motion or camera movement.
-
Which durations and resolutions does Seedance 2.5 image-to-video support?
The current request contract accepts integer durations from 4 to 30 seconds at 720p or 1080p. aspect_ratio is adaptive and follows the first frame. The four cases on this page cover 720p at four and five seconds; 30 seconds is a supported contract value with no page example yet.
-
How is Seedance 2.5 image-to-video priced?
Billing scales with output duration and resolution, with separate per-second tiers for 720p and 1080p. Check the live model price and task record for the final charge.
Create a generation task
https://api.hiapi.ai/v1/tasks Headers
AuthorizationstringRequiredAccount API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key
Content-TypestringOptionalThe request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.
Idempotency-KeystringOptionalIdempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.
On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.
Body
modelstringRequiredCurrent fixed value: seedance-2.5/reference-to-video
routestringOptionalCurrent fixed value: default
inputobjectRequired
Business parameters for seedance-2.5/reference-to-video and route default — see the parameter table below.
promptstringRequiredGeneration instruction describing how to use the reference assets; reference items in order as @image1, @video1, @audio1. This model is for reference-guided generation and does not support video editing or continuation.
durationintegerOptionalDefault: 5Output video duration in seconds; pass -1 for automatic duration, or an integer between 4 and 30. Default 5.
-145678910Show all (20)
1112131415161718192021222324252627282930resolutionstringOptionalDefault: "480p"Output video resolution; supports 480p, 720p, 1080p. Default 480p.
480p720p1080pweb_searchbooleanOptionalDefault: falseWhether to allow the model to search the web for real-time information mentioned in the prompt. Default false.
aspect_ratiostringOptionalDefault: "adaptive"Output aspect ratio; adaptive means the model follows the aspect ratio of the reference assets. Default adaptive.
16:94:31:13:49:1621:9adaptiveoutput_formatstringOptionalDefault: "mp4"Output video container format; mp4 is the default format with better compatibility, while mov is intended for professional post-production. Default mp4.
mp4movgenerate_audiobooleanOptionalDefault: trueWhether to also generate dialogue, sound effects, and background audio. Default true.
reference_audio_urlsarrayOptionalmaxItems 10Array of reference audio URLs, up to 10 clips; each must be wav or mp3, no larger than 15 MB, 2 to 30 seconds long, and the cumulative audio duration must not exceed 30 seconds. When reference audio is provided, at least one reference video must also be provided.
Array [ string ]
reference_image_urlsarrayOptionalmaxItems 30Array of reference image URLs, up to 30 images; supports jpeg, png, webp, bmp, tiff, gif, each no larger than 30 MB, 300 to 6000 pixels per side, aspect ratio 0.4 to 2.5; SVG, HEIC, and HEIF are not supported.
Array [ string ]
reference_video_urlsarrayRequiredminItems 1maxItems 10Array of reference video URLs, up to 10 clips; each must be mp4 or mov, with total pixels of at least 409600 (e.g., 854x480 or higher), frame rate 24 to 60 fps, size no larger than 200 MB, 2 to 30 seconds long, 300 to 6000 pixels per side, aspect ratio 0.4 to 2.5, and the cumulative video duration must not exceed 30 seconds.
Array [ string ]
callbackobjectOptional
Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.
Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.
urlstringRequiredRequired when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.
whenstringOptionalDefault: "final"Only final is supported today — notified on both success and fail.
finalstoragestringOptionalDefault: "temp"Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.
temppersistentRequest examples
# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5/reference-to-video",
"input": {
"prompt": "…",
"duration": 5,
"resolution": "480p",
"web_search": false,
"aspect_ratio": "adaptive",
"output_format": "mp4",
"generate_audio": true,
"reference_video_urls": "…"
}
}' const res = await fetch("https://api.hiapi.ai/v1/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "seedance-2.5/reference-to-video",
input: {
"prompt": "…",
"duration": 5,
"resolution": "480p",
"web_search": false,
"aspect_ratio": "adaptive",
"output_format": "mp4",
"generate_audio": true,
"reference_video_urls": "…"
}
}),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } } import os, requests
res = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "seedance-2.5/reference-to-video",
"input": {
"prompt": "…",
"duration": 5,
"resolution": "480p",
"web_search": False,
"aspect_ratio": "adaptive",
"output_format": "mp4",
"generate_audio": True,
"reference_video_urls": "…"
}
},
)
print(res.json()) # { code, message, data: { taskId } } 200 OK
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
}
} 400 Bad Request
{
"code": 400,
"message": "invalid request",
"data": null,
"error_code": "INVALID_REQUEST"
} Get task detail
https://api.hiapi.ai/v1/tasks/:id Response fields
taskIdstringRequiredTask ID, always prefixed with tk-hiapi-.
modelstringRequiredResolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.
routestringOptionalPresent only when the task was submitted with an explicit route parameter; echoes the submitted value.
statusstringRequiredTask status.
queued Queued, not started yet.
handling Being processed.
archiving Processing finished, artifacts being prepared.
success Terminal: completed, artifacts available (output returned).
fail Terminal: failed (error returned).
After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.
creatednumberRequiredTask creation time (Unix seconds).
completednumberRequiredUnix seconds when the task reached a terminal state; fixed to 0 while not terminal.
outputarrayOptional
Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).
Array [ object ]
Array items
urlstringRequiredArtifact URL, directly downloadable.
typestringRequiredCurrent possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.
expireAtnumberRequiredUnix seconds until which the artifact remains accessible; download or transfer before it expires.
errorobjectOptional
Present only when status == fail.
codestringRequiredBusiness error code.
messagestringRequiredError description.
Response examples
Success
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
"model": "happyhorse-1-0",
"status": "success",
"created": 1777282033,
"completed": 1777282099,
"output": [
{
"url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
"type": "video",
"expireAt": 1777886899
}
]
}
} Processing (non-terminal)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} Failed
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "fail",
"created": 1777282033,
"completed": 1777282099,
"error": {
"code": "TASK_FAILED",
"message": "task failed"
}
}
} Articles
View all articles →Related Models
View all models →Same Type
-
Runway Gen 4.5 Runway $0.172 /second -
Wan 3.0 Video Alibaba $0.040 /second -
Gemini Omni 1.1 Flash Google $0.450 /video -
FLUX 3 Video Black Forest Labs $0.090 /second -
Veo 3.1 Fast Google $0.170 /second -
Seedance 2.5 ByteDance $0.121 /second -
Wan 2.6 Flash Alibaba $0.043 /second -
Kling AI Avatar Kuaishou -- -
Grok Imagine 1.5 xAI $0.011 /second -
Veo 3.1 Lite Google $0.060 /second -
Seedance 2.0 ByteDance $0.017 /second -
HeyGen Avatar V HeyGen $0.150 /second