Skip to content
HiAPI Docs
HiAPI
Playground Get API Key
English
English 中文

Seedance 2.5 Reference to Video API

POST /v1/tasks

Image, video, and audio models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model seedance-2.5/reference-to-video
Capability Multimodal reference-to-video
Reference media Images / video / audio
Duration 4-30 seconds

Generate up to 30 seconds from 1-10 reference videos, optionally combined with reference images and audio.

Production guidance

Calling the API
  • Use callback.url for terminal notifications and GET /v1/tasks/:id as a fallback query.
  • Artifact URLs expire; copy files you need to keep into persistent storage.

Best suited for

Subject and style references

Use reference images to keep a subject, product, wardrobe, or art direction consistent.

reference_image_urls
Motion and camera references

Use reference videos to guide action, timing, camera movement, and scene changes.

reference_video_urls
Audio references

Use reference audio to guide voice and sound style.

reference_audio_urls

Request parameters

model string required

Model ID.

example seedance-2.5/reference-to-video
input object required

Multimodal reference-to-video parameters.

prompt string required

Motion, camera, and scene instructions. Refer to assets in order as @image1, @video1, or @audio1. Video editing and extension are not supported.

reference_video_urls string[] required

Array of 1-10 reference video URLs. Supports mp4 and mov; each clip is 2-30 seconds, under 200 MB, and 24-60 fps; combined duration is limited to 30 seconds.

reference_image_urls string[] optional

Array of up to 30 reference image URLs. Supports jpeg, png, webp, bmp, tiff, gif, heic, and heif; under 30 MB each; each side 300-6000 px; aspect ratio 0.4-2.5. SVG is not supported.

reference_audio_urls string[] optional

Array of up to 10 reference audio URLs. Supports wav and mp3; each clip is 2-30 seconds and under 15 MB; combined duration is limited to 30 seconds.

resolution enum optional

Output video resolution. Defaults to 480p.

default 480p enum: 480p720p
duration integer optional

Output duration in seconds. Accepts integers from 4 to 30 and defaults to 5 seconds.

default 5
aspect_ratio enum optional

Output aspect ratio. adaptive selects a ratio from the prompt and reference media.

default adaptive enum: 16:94:31:13:49:1621:9adaptive
generate_audio boolean optional

Generate synchronized dialogue, effects, and background audio.

default true
output_format enum optional

Output format. mp4 has broad compatibility; mov is intended for professional post-production.

default mp4 enum: mp4mov
web_search boolean optional

Allow the model to search for current information mentioned in the prompt.

default false
callback object optional

Sends the task object when the task reaches a terminal state; the polling endpoint wraps the same object in data.

url string required

HTTPS URL that receives terminal notifications.

example https://your-domain.com/hiapi/callback
when enum optional

Triggers when the task reaches a terminal state.

default final enum: final

Example requests

Video and image references

Combine a motion video with a subject image.

Request body
{
  "model": "seedance-2.5/reference-to-video",
  "input": {
    "prompt": "Keep the subject appearance and use a smooth follow shot",
    "reference_video_urls": [
      "https://example.com/camera-motion.mp4"
    ],
    "reference_image_urls": [
      "https://example.com/subject.jpg"
    ],
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "16:9"
  }
}
Video and audio references

Combine a motion reference with a voice reference.

Request body
{
  "model": "seedance-2.5/reference-to-video",
  "input": {
    "prompt": "Keep the action timing and change the scene to a city at night",
    "reference_video_urls": [
      "https://example.com/motion.mp4"
    ],
    "reference_audio_urls": [
      "https://example.com/voice.wav"
    ],
    "resolution": "480p",
    "duration": 8,
    "aspect_ratio": "adaptive"
  }
}
Up to ten reference videos

Pass 1-10 reference videos with a combined duration of no more than 30 seconds.

Request body
{
  "model": "seedance-2.5/reference-to-video",
  "input": {
    "prompt": "Blend the camera rhythm from these clips into one coherent scene",
    "reference_video_urls": [
      "https://example.com/clip-01.mp4",
      "https://example.com/clip-02.mp4"
    ],
    "resolution": "720p",
    "duration": 10,
    "aspect_ratio": "adaptive"
  }
}

Getting the result

  1. Read data.taskId from the create-task response.
  2. Wait for the callback or query GET /v1/tasks/:id; polling puts the task under data.
  3. When status=success, read the video URL from output type=video; a callback reads output directly.

FAQ

How do callback and polling responses differ?

They contain the same task fields but use different HTTP envelopes: polling puts the task under data, while the callback body is the task object itself.

Do reference videos and audio change output duration?

No. duration controls output length; reference media only guides the content.

Next steps