Use Reference Image 1 only for the compact rover's rounded white crackle-ceramic body, four cobalt-blue wheels, brass sensor mast, dark glass sensor band, folded sampling arm, proportions, and materials. Use Reference Video 1 only for the curved route, quick right-left correction, stop timing, and low constant-distance camera track; do not copy the brass beetle, wooden blocks, washer, or worktable. Use Reference Audio 1 only for movement cadence and stop cue; replace leg taps with wheel and greenhouse sounds. Create one continuous four-second shot inside a misty glass greenhouse at dawn. The rover follows a curved wet-stone path between two empty planting beds, makes one right-left correction, then stops beneath a dripping irrigation pipe. Preserve the referenced rover identity, four wheels, and body geometry throughout. Synchronized audio: four wheels on wet stone, quiet electric steering, one water drop, and ventilation ambience. No cuts, no insects, no worktable, no blocks, no extra vehicles, no people, no readable text, no logos, no brands, no products, no advertising, no watermark.
Seedance 2.0 Fast Reference-to-Video
seedance-2.0-fast/reference-to-videoSeedance 2.0 Fast Reference-to-Video creates a new 4–15 second clip from a prompt plus reference images, videos, and optional audio. Images guide appearance, videos guide motion and camera rhythm, and audio guides sound; at least one image or video is required, with 12 assets maximum.
Input
Advanced
Generate audio
Ask the model to generate an audio track with the video.
Return last frame
Keep the video result and request the final frame as an additional file.
Web search
Send the optional web-assisted generation field.
Output
IdleYour generated files will appear here
Set the inputs, choose a duration, then run the asynchronous video task.
Continue with
Examples
REST API
Quick Start
Authenticate, submit the smallest valid Reference-to-Video request, then retrieve the asynchronous video result.
Connect to the Vidgo API
Create an API key, store it only on your server, and send it as a Bearer header.
- Endpoint
- POST
https://api.vidgo.ai/api/generate/submit - Authentication
- Authorization: Bearer VIDGO_API_KEY
Submit one generation task
Send the exact model ID and required mode fields; success immediately returns task_id.
curl --request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "seedance-2.0-fast/reference-to-video",
"callback_url": "https://httpbin.org/post",
"input": {
"prompt": "Use Reference Image 1 only for the compact rover's rounded white crackle-ceramic body, four cobalt-blue wheels, brass sensor mast, dark glass sensor band, folded sampling arm, proportions, and materials. Use Reference Video 1 only for the curved route, quick right-left correction, stop timing, and low constant-distance camera track; do not copy the brass beetle, wooden blocks, washer, or worktable. Use Reference Audio 1 only for movement cadence and stop cue; replace leg taps with wheel and greenhouse sounds. Create one continuous four-second shot inside a misty glass greenhouse at dawn. The rover follows a curved wet-stone path between two empty planting beds, makes one right-left correction, then stops beneath a dripping irrigation pipe. Preserve the referenced rover identity, four wheels, and body geometry throughout. Synchronized audio: four wheels on wet stone, quiet electric steering, one water drop, and ventilation ambience. No cuts, no insects, no worktable, no blocks, no extra vehicles, no people, no readable text, no logos, no brands, no products, no advertising, no watermark.",
"duration": 4,
"resolution": "480p",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-fast/reference-to-video/v1/input-reference-image.png"
],
"reference_video_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-fast/reference-to-video/v1/input-reference-video.mp4"
],
"reference_audio_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-fast/reference-to-video/v1/input-reference-audio.mp3"
],
"generate_audio": true,
"seed": 26082706
}
}'Wait for the result
Poll only not_started or running, or receive the flat terminal object at callback_url.
Track status
GET https://api.vidgo.ai/api/generate/status/I4FDXYJ7C1LQT4H2Begin near a 2 second polling interval, back off for long tasks, and enforce a timeout. finished and failed are terminal. Handle network failure, request timeout, and task failure separately; callback_url uses the same request contract.
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "I4FDXYJ7C1LQT4H2",
"status": "running",
"created_time": "2026-08-27T14:38:03"
}
}{
"code": 200,
"data": {
"task_id": "I4FDXYJ7C1LQT4H2",
"status": "finished",
"progress": 100,
"created_time": "2026-08-27T14:38:03",
"error_message": null,
"files": [
{
"file_type": "video",
"file_url": "https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-fast/reference-to-video/v1/output.mp4"
}
]
}
}Complete runnable example
The example checks HTTP and business codes, task_id, backoff, timeout, terminal states, and result files.
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "seedance-2.0-fast/reference-to-video",
"callback_url": "https://httpbin.org/post",
"input": {
"prompt": "Use Reference Image 1 only for the compact rover's rounded white crackle-ceramic body, four cobalt-blue wheels, brass sensor mast, dark glass sensor band, folded sampling arm, proportions, and materials. Use Reference Video 1 only for the curved route, quick right-left correction, stop timing, and low constant-distance camera track; do not copy the brass beetle, wooden blocks, washer, or worktable. Use Reference Audio 1 only for movement cadence and stop cue; replace leg taps with wheel and greenhouse sounds. Create one continuous four-second shot inside a misty glass greenhouse at dawn. The rover follows a curved wet-stone path between two empty planting beds, makes one right-left correction, then stops beneath a dripping irrigation pipe. Preserve the referenced rover identity, four wheels, and body geometry throughout. Synchronized audio: four wheels on wet stone, quiet electric steering, one water drop, and ventilation ambience. No cuts, no insects, no worktable, no blocks, no extra vehicles, no people, no readable text, no logos, no brands, no products, no advertising, no watermark.",
"duration": 4,
"resolution": "480p",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-fast/reference-to-video/v1/input-reference-image.png"
],
"reference_video_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-fast/reference-to-video/v1/input-reference-video.mp4"
],
"reference_audio_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-fast/reference-to-video/v1/input-reference-audio.mp3"
],
"generate_audio": true,
"seed": 26082706
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
while true; do
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/I4FDXYJ7C1LQT4H2" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep 2
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
doneRequest Parameters
model and optional callback_url are top-level; generation fields belong in input, and unsupported media is rejected.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| model | string | Yes | — | Must equal seedance-2.0-fast/reference-to-video. |
| callback_url | string (URL) | No | — | Public HTTP(S) endpoint for the terminal task object. |
| input | object | Yes | — | Contains only fields public for this mode. |
| input.prompt | string | Required | — | Trimmed length 1–20,000; the Playground supplies a mode-specific example. |
| input.duration | integer | Required | — | Any integer from 4 through 15 inclusive; Playground default 5. |
| input.resolution | string | Required | 720p | 480p, 720p; Playground default 720p. |
| input.aspect_ratio | string | Optional | 16:9 | auto, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16; Playground default 16:9. |
| input.reference_image_urls | string[] | Conditional | — | Up to 9 public image URLs; an image or video is required. |
| input.reference_video_urls | string[] | Conditional | — | Up to 3 public video URLs; each duration is floored separately and added to billed seconds. |
| input.reference_audio_urls | string[] | Optional | — | Up to 3 public audio URLs. Audio cannot stand alone; all reference assets total at most 12. |
| input.generate_audio | boolean | Optional | true | Boolean. The Playground explicitly sends true by default. |
| input.return_last_frame | boolean | Optional | false | Boolean. The Playground explicitly sends false by default. |
| input.web_search | boolean | Optional | false | Boolean. The Playground explicitly sends false by default. |
| input.seed | integer | Optional | — | Integer with no published range; omitted when empty. |
| Rejected media fields | — | — | — | image_urls, start_image_url, end_image_url, video_url, video_urls; _reference_video_billing_seconds is internal |
Response Fields
Submission identifies the task; status adds progress, every result file, or failure detail.
| Field | Type | Description |
|---|---|---|
| code | integer | Business code; success accepts 0 or 200. |
| message | string | Optional response or error message. |
| data.task_id | string | Task ID used by the status endpoint. |
| data.status | string | not_started, running, finished, or failed. |
| data.created_time | string | Task creation timestamp. |
| data.progress | integer | Reported completion percentage. |
| data.files[] | array | All result files in returned order. |
| data.files[].file_url | string | Direct result URL. |
| data.files[].file_type | string | Public type such as video or image. |
| data.files[].watermark_url | string | null | Watermarked URL when returned by the status service. |
| data.error_message | string | null | Failure detail for a failed task. |
Task Lifecycle
not_started and running are non-terminal; finished and failed are terminal.
not_startedAccepted and waiting to begin.
runningGeneration is active; continue polling with backoff.
finishedSuccessful terminal state; read every file.
failedFailed terminal state; read error_message and stop.
Polling and Errors
- Authentication401 means the Bearer key is missing or invalid; correct it before retrying.
- Validation400 means the payload violates this endpoint contract; fix the named field.
- Insufficient balanceTreat balance errors separately and show required credits and USD.
- Polling and timeoutBegin around 2 seconds and back off; network failure and client timeout are not task failed.
- Terminal states and callbackStop on finished or failed; callback_url can receive the same task as a flat terminal object.
Model Specifications
| Specification | Value | Details |
|---|---|---|
| Input mode | Prompt + references | At least one image or video. |
| Output | Asynchronous video task | May return multiple files, all preserved in order. |
| Resolution | 480p / 720p | Fast rejects 1080p and 4K. |
| Duration | 4–15 whole seconds | Inclusive boundaries. |
| Aspect ratio | 7 values | Auto plus six fixed ratios. |
| Billing basis | Output + reference-video seconds | With video, every billed second uses the with-video rate. |
Seedance 2.0 Fast Reference-to-Video
Seedance 2.0 Fast Reference-to-Video creates a new 4–15 second clip from a prompt plus reference images, videos, and optional audio. Images guide appearance, videos guide motion and camera rhythm, and audio guides sound; at least one image or video is required, with 12 assets maximum.
Why Choose This?
References have distinct jobs.Images, videos, and audio guide appearance, motion or camera, and sound or rhythm separately.
Lower current rates.Use 480p or 720p for cost-conscious iteration and repeated trials.
Continuous duration control.Select any whole-second duration from 4 through 15 instead of a short preset list.
Explicit advanced controls.Request audio, a returned last frame, web assistance, and an optional integer seed.
Parameters
| Parameter | Requirement | Description |
|---|---|---|
| prompt | Required | Trimmed length 1–20,000; the Playground supplies a mode-specific example. |
| duration | Required | Any integer from 4 through 15 inclusive; Playground default 5. |
| resolution | Required | 480p, 720p; Playground default 720p. Default 720p480p |
| aspect_ratio | Optional | auto, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16; Playground default 16:9. Default 16:99:161:121:94:33:4auto |
| reference_image_urls | Conditional | Up to 9 public image URLs; an image or video is required. |
| reference_video_urls | Conditional | Up to 3 public video URLs; each duration is floored separately and added to billed seconds. |
| reference_audio_urls | Optional | Up to 3 public audio URLs. Audio cannot stand alone; all reference assets total at most 12. |
| generate_audio | Optional | Boolean. The Playground explicitly sends true by default. Default true |
| return_last_frame | Optional | Boolean. The Playground explicitly sends false by default. Default false |
| web_search | Optional | Boolean. The Playground explicitly sends false by default. Default false |
| seed | Optional | Integer with no published range; omitted when empty. |
How to Use
Assign each referenceUse images for appearance, videos for motion or camera, and audio for sound or rhythm.
Direct the movementUse concrete verbs and separate subject motion from camera motion.
Set the outputChoose 480p, 720p, a 4–15 second duration, and the applicable composition.
Review advanced controlsConfirm audio, last-frame, web-assistance, and seed choices.
Submit and trackRun the request, then poll the task ID or process its terminal callback.
Pricing
One credit equals $0.005. Without reference video, bill output duration. With video, add each separately floored reference duration and apply the with-video rate to every billed second.
| Usage | Rate | Details |
|---|---|---|
| 480p billing | 14 / 9 credits per billed second | $0.070/s without reference video; $0.045/billed second with reference video, including its duration. |
| 720p billing | 28 / 20 credits per billed second | $0.140/s without reference video; $0.100/billed second with reference video, including its duration. |
Best Use Cases
Character-guided shotsUse a character image for appearance and a video reference for motion guidance in a new shot.
Motion referenceUse a source video's action and camera rhythm to guide a new clip.
Brand visualsUse image references to retain a product, character, or visual language.
Rhythm-led clipsUse an audio reference to establish intended sound or beat.
Pro Tips
- Order the prompt as subject and setting, action, camera, light and mood, then sound intent.
- Name the job of each reference in the prompt so guidance does not conflict.
- Use concrete motion verbs and separate subject movement from camera movement.
- Choose composition before describing where the subject sits in frame.
- When timing matters, describe an opening, development, and final beat.
Notes
- Use at most 9 images, 3 videos, 3 audio files, and 12 references total; audio cannot stand alone.
- resolution is required by the public OpenAPI, so examples and the Playground always send it explicitly.
- _reference_video_billing_seconds is internal and must never appear in a frontend or API request.
- Fast accepts only 480p and 720p, not 1080p or 4K.
- Tasks are asynchronous; poll only while status is not_started or running.
Related Models
Frequently Asked Questions about Seedance 2.0 Fast Reference-to-Video API
What is the Seedance 2.0 Fast Reference-to-Video API?
Seedance 2.0 Fast is a ByteDance Seedance model. This Reference-to-Video endpoint accepts a prompt plus image, video, and optional audio references, then returns an asynchronous video-generation task through the documented REST request contract.
How do I call the Seedance 2.0 Fast Reference-to-Video API?
Send POST /api/generate/submit with Authorization: Bearer VIDGO_API_KEY. A successful response includes task_id for the unified status endpoint.
How much does the Seedance 2.0 Fast Reference-to-Video API cost?
Without reference video, multiply output seconds by the without-video rate. With video, add every separately floored reference duration to output duration and multiply every billed second by the with-video rate. 480p: 14 credits ($0.070)/s; 720p: 28 credits ($0.140)/s.
What inputs does the Seedance 2.0 Fast Reference-to-Video API accept?
It accepts a prompt, up to 9 reference images, 3 videos, and 3 audio files, with 12 assets total. An image or video is required, and audio cannot stand alone.
How do I get the generated video?
Poll GET /api/generate/status/{task_id}, or submit callback_url. Continue only for not_started or running; read every data.files[].file_url after finished, and stop with the error after failed.
Which Seedance 2.0 endpoint should I choose?
Choose Text with no source asset, Image for a start or start/end frame, and Reference for image, video, or audio guidance. Standard offers resolutions through 4K; Fast is limited to 480p/720p at lower current rates.


