Seedance 2.0 Mini Reference-to-Video API

bytedance/seedance-2.0-mini/reference-to-video

Seedance 2.0 Mini Reference-to-Video API uses a prompt plus image, video, and optional audio references to generate a 4–15 second video at 480p or 720p. A request accepts up to 9 images, 3 videos, and 3 audio files, with no more than 12 files total and at least one image or video.

Input

Prompt

0/20000

Reference images

0/9

Add image

Reference videos

0/3

Add video

Reference audio

0/3

Add audio

Total references0/12

Resolution

Duration

Aspect ratio

Generate audio

Ask the model to generate an audio track with the video.

Advanced

Return last frame

Keep the video result and request the final frame as an additional file.

Web search

Send the optional web_search Boolean field.

Seed

Output

Idle

Your generated files will appear here

Set the inputs, choose a duration, then run the asynchronous video task.

Continue with

Seedance 2.0 Mini Text-to-Video Seedance 2.0 Mini Image-to-Video

Examples

Use Reference Image 1 only for the fictional courier's face, short dark curly hair, cobalt-blue waterproof jacket, charcoal trousers, gray gloves, body proportions, and blue electric cargo tricycle. Use Reference Video 1 only for the start-and-pull-away action, natural weight shift, low side-tracking camera path, wet-road tire spray, and action timing; do not copy its amber-coated rider, red scooter, noodle stall, or night-market layout. Use Reference Audio 1 only for the engine-start cue, rain intensity, tire hiss, and timing; do not add music. Create one continuous four-second shot under the covered flower-market arcade shown by the reference identity: the courier mounts the blue cargo tricycle, starts it, and pulls forward past the flower buckets while preserving the referenced face, clothing, vehicle, roof, and wet-stone setting. No cuts, no extra people, no dialogue, no readable text, no logos, no products, no advertising, no watermark.

REST API

Quick Start

Authenticate, submit one public reference image, then retrieve every file from the asynchronous result.

Connect to the Vidgo API

Keep VIDGO_API_KEY on your server and send it as a Bearer token.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one generation task

The smallest valid request includes a prompt, duration, and one reference image or video.

Submit request

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-mini/reference-to-video",
  "callback_url": "https://webhook.site/b3fc9007-e1ec-4df1-97da-fd65c209e5d6",
  "input": {
    "prompt": "Use Reference Image 1 only for the fictional courier's face, short dark curly hair, cobalt-blue waterproof jacket, charcoal trousers, gray gloves, body proportions, and blue electric cargo tricycle. Use Reference Video 1 only for the start-and-pull-away action, natural weight shift, low side-tracking camera path, wet-road tire spray, and action timing; do not copy its amber-coated rider, red scooter, noodle stall, or night-market layout. Use Reference Audio 1 only for the engine-start cue, rain intensity, tire hiss, and timing; do not add music. Create one continuous four-second shot under the covered flower-market arcade shown by the reference identity: the courier mounts the blue cargo tricycle, starts it, and pulls forward past the flower buckets while preserving the referenced face, clothing, vehicle, roof, and wet-stone setting. No cuts, no extra people, no dialogue, no readable text, no logos, no products, no advertising, no watermark.",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-image.png"
    ],
    "reference_video_urls": [
      "https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-video.mp4"
    ],
    "reference_audio_urls": [
      "https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-audio.mp3"
    ],
    "generate_audio": true,
    "seed": 24082403
  }
}'

Wait for the result

Poll non-terminal states or provide callback_url; preserve every successful returned file.

Track status

GET https://api.vidgo.ai/api/generate/status/KV7E99PXH1WTZJDD

Poll at 2–5 seconds initially and back off for long tasks. Stop on finished or failed. A timeout or network error is separate from a failed task; callback_url receives a flat terminal task body.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "KV7E99PXH1WTZJDD",
    "status": "running",
    "created_time": "2026-08-24T09:01:21"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "KV7E99PXH1WTZJDD",
    "status": "finished",
    "created_time": "2026-08-24T09:01:21",
    "progress": 100,
    "error_message": null,
    "files": [
      {
        "file_type": "video",
        "file_url": "https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/output.mp4"
      }
    ]
  }
}

Complete runnable example

The expanded script handles submission, polling, failure, timeout, and file extraction.

Complete runnable example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "seedance-2.0-mini/reference-to-video",
  "callback_url": "https://webhook.site/b3fc9007-e1ec-4df1-97da-fd65c209e5d6",
  "input": {
    "prompt": "Use Reference Image 1 only for the fictional courier's face, short dark curly hair, cobalt-blue waterproof jacket, charcoal trousers, gray gloves, body proportions, and blue electric cargo tricycle. Use Reference Video 1 only for the start-and-pull-away action, natural weight shift, low side-tracking camera path, wet-road tire spray, and action timing; do not copy its amber-coated rider, red scooter, noodle stall, or night-market layout. Use Reference Audio 1 only for the engine-start cue, rain intensity, tire hiss, and timing; do not add music. Create one continuous four-second shot under the covered flower-market arcade shown by the reference identity: the courier mounts the blue cargo tricycle, starts it, and pulls forward past the flower buckets while preserving the referenced face, clothing, vehicle, roof, and wet-stone setting. No cuts, no extra people, no dialogue, no readable text, no logos, no products, no advertising, no watermark.",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-image.png"
    ],
    "reference_video_urls": [
      "https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-video.mp4"
    ],
    "reference_audio_urls": [
      "https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-audio.mp3"
    ],
    "generate_audio": true,
    "seed": 24082403
  }
}
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/KV7E99PXH1WTZJDD" \
    --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
done

Request Parameters

model and callback_url are top-level. input accepts common controls plus the three reference arrays; internal billing fields are never public input.

Field	Type	Required	Default	Description
model	string	Yes	—	Must be seedance-2.0-mini/reference-to-video.
callback_url	string (URL)	No	—	Public terminal callback endpoint.
input	object	Yes	—	Model-specific input object.
input.prompt	string	Yes	—	Trimmed length 1–20,000.
input.reference_image_urls	string[]	Conditional	—	Up to 9; an image or video is required.
input.reference_video_urls	string[]	Conditional	—	Up to 3; durations affect billing.
input.reference_audio_urls	string[]	No	—	Up to 3; cannot be used alone. All arrays total at most 12.
input.duration	integer	Yes	—	Inclusive 4–15.
input.resolution	string	No	720p	480p or 720p.
input.aspect_ratio	string	No	—	auto, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16.
input.generate_audio	boolean	No	—	Optional generated audio.
input.return_last_frame	boolean	No	—	Optional final-frame result.
input.web_search	boolean	No	—	Optional Boolean field.
input.seed	integer	No	—	Optional integer with no published range.

Response Fields

Submission returns task identity; status returns progress, all files, or a terminal error.

Field	Type	Description
code	integer	Business code; success uses 0 or 200.
message	string	Response message when present.
data.task_id	string	Status identifier.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Creation timestamp.
data.progress	integer	Reported progress.
data.files[]	array	Every successful file.
data.files[].file_url	string	Direct result URL.
data.files[].file_type	string	Returned media type.
data.files[].watermark_url	string \| null	Watermarked URL when available.
data.error_message	string \| null	Failure detail.

Task Lifecycle

Poll only non-terminal states.

not_started
Accepted and queued.
running
Generating; continue polling.
finished
Successful terminal state; read all files.
failed
Failed terminal state; stop and read the error.

Polling and Errors

Authentication401 means the Bearer key is missing or invalid.
Validation400 means a type, reference limit, total count, or condition is invalid.
Polling intervalStart around 2–5 seconds and back off for long tasks, 429, or 5xx.
Terminal statesStop on finished or failed and enforce a client timeout.
Callback optioncallback_url receives a flat terminal task object; polling remains available.

Model Specifications

Specification	Value	Details
Input mode	Image, video, and audio references	Up to 9 images, 3 videos, 3 audio files, and 12 total.
Output	Video + optional last frame	Asynchronous mixed-file result.
Resolution	480p / 720p	720p is the API default.
Duration	4–15 seconds	Inclusive integer range.
Visual requirement	Image or video	Audio cannot be submitted alone.
Billing basis	6–24 credits/s	Depends on resolution and whether any reference video is present.

View Seedance 2.0 Mini Reference-to-Video API documentation

Seedance 2.0 Mini Reference-to-Video API overview

Seedance 2.0 Mini Reference-to-Video API receives files through reference_image_urls, reference_video_urls, and reference_audio_urls. In prompt, state which appearance, action, camera, or sound information each file should provide.

Why use Seedance 2.0 Mini Reference-to-Video API?

Submit up to nine reference images.Images can provide subject, product, environment, wardrobe, or visual-style information.
Submit up to three reference videos.Videos can provide subject movement, action timing, and camera-movement information.
Submit up to three reference audio files.Audio can provide rhythm, ambience, sound-effect, or dialogue information, but cannot be submitted alone.
Combine three file types in one request.Images, videos, and audio can be submitted together, with no more than 12 files total.

Parameters

Parameter	Requirement	Description
prompt	Required	Trimmed instruction from 1 through 20,000 characters; explain each reference's role.
reference_image_urls	Conditional	Up to nine public image URLs. At least one image or video is required.
reference_video_urls	Conditional	Up to three public video URLs. Each duration is floored separately for billing.
reference_audio_urls	Optional	Up to three public audio URLs; audio cannot be the only reference type.
duration	Required	Integer output duration from 4 through 15 seconds; the Playground starts at 5.
resolution	Optional	480p or 720p; both API and Playground start at 720p. Default`720p480p`
aspect_ratio	Optional	Auto or six fixed ratios; the Playground starts at Auto. `auto16:99:161:121:94:33:4`
generate_audio	Optional	Boolean generated-audio request; the Playground sends true initially.
return_last_frame	Optional	Boolean request for an additional final-frame result.
web_search	Optional	Optional Boolean field.
seed	Optional	Integer with no published range.

How to Use

Assign each medium a jobUse images for appearance, video for movement and camera, and audio for sound or rhythm.
Add an image or video referenceProvide at least one image or video; audio alone is invalid.
Count the full setStay within 9 images, 3 videos, 3 audio files, and 12 files total.
Write explicit reference rolesTell the prompt which asset controls identity, action, camera, or sound.
Submit and trackRun the request, then poll the task ID or receive the terminal callback.

Pricing

Without reference video, only output seconds use the standard rate. With any reference video, output seconds plus the separately floored duration of each reference video use the lower with-video rate.

Usage	Rate	Details
480p without reference video	10 credits / output second	$0.050/s. A 5 second output uses 50 credits.
720p without reference video	24 credits / output second	$0.120/s. A 5 second output uses 120 credits.
480p with reference video	6 credits / billed second	$0.030/s × (output seconds + sum floor(each reference-video duration)).
720p with reference video	12.5 credits / billed second	$0.0625/s × (output seconds + sum floor(each reference-video duration)).

Best Use Cases

Character appearance and movement referencesSubmit character images for appearance information and motion footage for movement information.
Product appearance and operation referencesSubmit product images for design information and videos for movement or operation information.
Camera movement from reference videoIn prompt, request the pan, push, orbit, or tracking movement shown in a reference video.
Audio rhythm and sound referencesSubmit audio for rhythm, ambience, sound effects, or dialogue information alongside an image or video.

Pro Tips

State which image controls identity, wardrobe, environment, or style instead of saying only 'use the references'.
Describe a reference video's action and camera contribution as separate instructions.
Use audio for rhythm, ambience, dialogue, or sound effects, and always include an image or video.
Submit only files that support the current generation request, and remove references with conflicting content.
Check that every reference-video duration has loaded before showing an exact price estimate.

Notes

Limits are 9 images, 3 videos, 3 audio files, and 12 files total, not 15.
Audio alone is invalid; at least one reference image or video is required.
Reference-video seconds are floored per file before summing, and every billed second uses the with-video rate.
Reference-video billing seconds are calculated by the service and are not part of the public request input.
Unknown reference-video metadata produces a minimum estimate, never a fabricated exact total.

MiniMax H3Compare fixed-2K text-only, ordered-frame, and image, video, or audio reference modes.

Wan 2.6Create 1080p videos with text, image, or video-guided inputs.

Kling 2.6Generate short videos with optional synchronized dialogue and ambient audio.

Seedance 2.0 Mini Reference-to-Video API — Frequently asked questions

What is Seedance 2.0 Mini Reference-to-Video API?

Seedance 2.0 Mini Reference-to-Video API uses a prompt plus image, video, and optional audio references to generate video. A successful submission returns task_id; generated files are available in data.files after completion.

How do I call Seedance 2.0 Mini Reference-to-Video API?

Send POST /api/generate/submit with a Bearer key, set model to seedance-2.0-mini/reference-to-video, and provide prompt, duration, and at least one public image or video URL. Poll the returned task_id or provide callback_url.

How is Seedance 2.0 Mini Reference-to-Video API billed?

Without reference video, 480p uses 10 credits per output second and 720p uses 24. With reference video, 480p uses 6 credits per billed second and 720p uses 12.5; billed seconds equal output duration plus each reference-video duration floored separately.

What inputs does Seedance 2.0 Mini Reference-to-Video API accept?

A request accepts up to 9 images, 3 videos, and 3 audio files, with no more than 12 files total. At least one image or video is required, so audio cannot be submitted alone.

How do I retrieve a Seedance 2.0 Mini Reference-to-Video API result?

Poll the task only while status is not_started or running. Stop when status becomes finished or failed, then read all successful files from data.files or the failure detail from data.error_message.

How should I choose among the three Seedance 2.0 Mini APIs?

Use Seedance 2.0 Mini Reference-to-Video API for image, video, or audio references, Seedance 2.0 Mini Image-to-Video API for a required start frame and optional end frame, or Seedance 2.0 Mini Text-to-Video API without source media.