Seedance 2.5 Image-to-Video API

bytedance/seedance-2.5/image-to-video

Seedance 2.5 (Image-to-Video) generates audio-synchronized videos up to 30 seconds long from reference images and text prompts, with controls for camera movement, lighting, pacing, and sound. It helps preserve subjects, composition, and visual style across complex scenes while adding expressive motion, dialogue, music, and sound effects in a single generation.

Input

Prompt

727/20000

Start frame

Add start

A start frame is required; the end frame is never promoted automatically.

End frame

Add end

Resolution

Duration

Aspect ratio

Autoauto

Generate audio

Output

Idle

Your generated video will appear here

Configure the required inputs, resolution, and duration, then run the task.

Continue with

Seedance 2.5 Text-to-Video Seedance 2.5 Reference-to-Video

Examples

Begin exactly from Image 1 and finish on Image 2. In one continuous five-second shot, the pianist presses three gentle notes, lets both hands rise a few centimeters from the keys, then turns his head and shoulders toward the window as a light breeze moves the curtain. Use one slow, stable push-in only. Preserve the same face, hair, green sweater, seated position, piano, room layout, camera axis, and morning light throughout. Keep both hands anatomically natural and settle cleanly into the final pose without morphing. Synchronized audio: three soft piano notes, faint curtain rustle, and quiet room tone. No cuts, no extra person, no dialogue, no readable text, no logo, no product placement, no advertising, no watermark.

REST API

Quick Start

Authenticate, submit a valid input object, then use task_id to retrieve the video.

Connect to the Vidgo API

Create an API key, keep it only on your server, and send Authorization: Bearer VIDGO_API_KEY.

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

Submit one generation task

Run the smallest valid payload for this workflow. A successful submission immediately returns task_id without waiting for the video.

Submit request

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 '{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "The camera pushes in as the subject turns toward the window light.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "generate_audio": true,
    "image_urls": [
      "https://example.com/start-frame.jpg"
    ]
  }
}')

CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
  printf 'API error: %s
' "$RESPONSE" >&2
  exit 1
fi
printf '%s
' "$RESPONSE"

Wait for the result

Query with task_id, continue for not_started/running, and stop for finished/failed. On success, read data.files[].file_url.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll about every 2 seconds, then back off gradually. Continue only for not_started or running and stop on finished or failed. You can instead add callback_url to the same top-level request contract.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "running",
    "created_time": "2026-08-22T10:00:00Z"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-08-22T10:00:00Z",
    "progress": 100,
    "error_message": null
  }
}

Complete runnable example

Expand for a complete script with HTTP and business-code checks, task_id validation, polling, terminal-state handling, and a timeout boundary.

Complete runnable example

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

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "The camera pushes in as the subject turns toward the window light.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "generate_audio": true,
    "image_urls": [
      "https://example.com/start-frame.jpg"
    ]
  }
}
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')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
  printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
  if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
    printf 'Timed out after 600 seconds
' >&2
    exit 1
  fi
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
  BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
  if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
    printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
    exit 1
  fi

  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 "$POLL_DELAY"
      if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Input parameters

These are the fields accepted inside input. The request example shows the required top-level model field.

Field	Type	Required	Default	Description
prompt	string	Yes	—	1–20,000 characters after trimming.
duration	integer	Yes	—	An integer from 4 through 30, inclusive.
resolution	string	Yes	—	Send 480p or 720p explicitly.
aspect_ratio	string	No	—	Must be auto when provided.
generate_audio	boolean	No	—	Whether to request an audio track; the playground always sends true or false.
image_urls	string[]	Yes	—	One required Start frame and one optional End frame. Preserve order; use public, directly downloadable URLs.

Response Fields

Submission returns task identity immediately. Status responses add progress, every output file, or a failure message.

Field	Type	Description
code	integer	Application result code; successful responses use 0 or 200.
message	string	Human-readable message or error detail when present.
data.task_id	string	Task ID used in the status endpoint path.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation time in date-time format.
data.progress	integer	0–100 progress when reported by the provider.
data.files[]	array	All output files from a successful task, in response order.
data.files[].file_url	string	Public URL for a generated video.
data.files[].file_type	string	File type, such as video.
data.error_message	string \| null	Failure detail when status is failed.

Task Lifecycle

Treat not_started and running as non-terminal states. finished and failed are terminal alternatives; stop polling when either is returned.

not_started
The task was accepted and is waiting to begin.
running
Generation is in progress. Continue polling the same task_id.
finished
Generation succeeded. Read every video URL from data.files[].file_url.
failed
Generation stopped with an error. Read data.error_message and stop polling.

Polling and Errors

AuthenticationA 401 response means the Bearer API key is missing or invalid. Correct it before retrying.
ValidationA 400 response identifies an invalid field, unsupported media key, or insufficient credit balance. Correct the request before resubmitting.
Network and timeoutA transport failure is different from a failed task. Retry status checks with a bounded timeout before deciding that the task failed.
Polling intervalStart around every 2 seconds and increase the interval gradually for a long-running task.
Terminal statesContinue only for not_started or running. Stop immediately on finished or failed.
Callback optionProvide callback_url at the request top level to receive the final flat task object; polling remains available if delivery fails.

Endpoint limits

Specification	Value	Details
Input mode	1–2 frames	The first image is Start; the second image is optional End.
Output	Video task	The endpoint returns an asynchronous task ID.
Resolution	480p / 720p	resolution is required and sent explicitly.
Duration	4–30 seconds	Every integer value in the inclusive range is valid.
Aspect ratio	auto only	This workflow uses auto framing.
Billing basis	Output seconds	480p uses 28 credits/s; 720p uses 63 credits/s.

View Seedance 2.5 Image-to-Video API documentation

Seedance 2.5 Image-to-Video

Seedance 2.5 Image-to-Video turns a reference image and text prompt into a continuous scene with synchronized sound. Use the prompt to direct subject action, camera movement, lighting, and pacing while the model carries the source image’s subject, composition, and visual style into the generated video.

Why Choose This?

Begin from an approved visualUse an existing subject, product, setting, and composition as the starting point for the shot.
Direct what changes after the frameDescribe the action, pace, expression, environmental movement, and physical change that should follow the image.
Guide the final stateAdd an optional end frame when the final pose, product state, or composition needs a visual destination.
Separate subject motion from camera motionDescribe subject movement first, then add camera direction, shot size, lighting, and atmosphere as distinct instructions.
Coordinate motion with soundEnable generated audio when ambience, action sounds, dialogue, or music cues should develop with the image.

Parameters

Parameter	Requirement	Description
prompt	Required	String. Directs action, camera movement, visual change, and sound intent after the start frame; 1–20,000 characters after trimming.
image_urls	Required	String array with one or two public, directly downloadable URLs. The first image is Start; the optional second image is End. Preserve this order.
duration	Required	Integer. Sets output length from 4 through 30 seconds, inclusive; the Playground preselects 5 seconds.
resolution	Required	String. Sets output resolution and must be sent explicitly; the Playground preselects 720p. `720p480p`
aspect_ratio	Optional	String. Uses auto framing for this workflow; the Playground displays it as read-only and sends it explicitly. `auto`
generate_audio	Optional	Boolean. Requests a generated audio track; the Playground preselects true and explicitly sends either value. `truefalse`

How to Use

Choose a decisive opening imageUse a frame with the subject, lighting, composition, and negative space you want at the start of the shot.
Describe the first visible actionContinue from what is already present: the watch face catches the light as the hand slowly turns toward camera.
Direct the camera separatelyAdd a second instruction for the lens and movement: macro close-up, slow orbit, shallow focus, soft studio reflections.
Add an end frame when neededAdd the optional second image only when it clarifies the final pose, arrangement, or visual transition.
Configure the outputSet 480p or 720p, a whole-second duration from 4 to 30, and the audio control; framing follows auto.
Generate and reviewRun the request, inspect how the subject, composition, motion, and ending relate, then revise the prompt or frame pair for the next pass.

Pricing

Price depends only on output duration and resolution; the audio toggle and media count do not change the rate.

Usage	Rate	Details
480p	28 credits/output sec ($0.140/sec)	4 seconds costs 112 credits ($0.560), 5 seconds costs 140 credits ($0.700), and 30 seconds costs 840 credits ($4.20).
720p	63 credits/output sec ($0.315/sec)	4 seconds costs 252 credits ($1.26), 5 seconds costs 315 credits ($1.58), and 30 seconds costs 1,890 credits ($9.45).

Best Use Cases

Product revealsAnimate an approved product still with rotation, material movement, light changes, or a camera pass for a launch teaser.
Character performance clipsTurn a portrait or character keyframe into a performance clip by directing expression, gesture, gaze, and camera response.
Designed visual transitionsConnect compatible opening and ending frames into a transition study for a transformation, reveal, or composition change.
Campaign key visuals in motionAdapt an existing campaign still into a short motion asset for social, display, or presentation use.

Pro Tips

Treat the image as the opening sentence. Use the prompt to explain what happens next, not to inventory details that are already visible.
Replace 'make the portrait move' with a visible progression: she looks toward the window, exhales, then turns back as the camera slowly pushes in.
Write subject movement and camera movement as separate instructions so neither one has to imply the other.
When two frames are used, keep identity, lighting logic, and art direction compatible across both images.
Compose the source image carefully because this endpoint keeps aspect_ratio on auto.

Notes

image_urls preserves Start, then optional End order across one or two public, directly downloadable HTTP(S) URLs.

Seedance 2Use the earlier Seedance family for text, frames, and multimodal references.

Kling 2.6Create video with text or image guidance and optional generated audio.

Wan 2.6Generate 1080p video through text, image, or video-guided workflows.

Seedance 2.5 Image To Video API — Frequently asked questions

What is the Seedance 2.5 Image-to-Video API?

Seedance 2.5 is developed by ByteDance Seed. The Image-to-Video API turns one required start-frame image and a text prompt into an asynchronously generated video. You can also add an optional end frame to guide the ending and request synchronized audio.

How do I call the Seedance 2.5 Image-to-Video API?

Send POST /api/generate/submit with a Bearer API key, set model to seedance-2.5/image-to-video, and place every generation field inside input. A successful submission returns task_id immediately; the API tab and linked documentation include runnable examples.

Open the complete API documentation

How much does the Seedance 2.5 Image-to-Video API cost?

480p costs 28 credits/output second and 720p costs 63. For example, 5 seconds costs 140 credits ($0.700) at 480p or 315 credits ($1.58) at 720p.

What inputs does the Seedance 2.5 Image-to-Video API accept?

Inside input, image_urls must contain one Start URL and may contain one End URL in that order. The array accepts one or two items total, and aspect_ratio can only be auto.

How do I get the generated video?

Poll GET /api/generate/status/{task_id} with task_id. On finished, read data.files[].file_url; on failed, stop and read the error. You can also provide callback_url for the terminal result.

Which Seedance 2.5 endpoint should I choose?

Choose Image-to-Video when an existing frame should define how the shot begins. Use Text-to-Video for language-only creation, or Reference-to-Video when several assets need separate appearance, motion, camera, or sound roles.