Seedance 2.5 Reference to Video API
POST Base URL:
https://api.hiapi.ai /v1/tasks Image, video, and audio models are called through theUnified 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 |
| Output duration | 4-30 seconds, or -1 for automatic selection |
Generate a new video using reference clips to guide action and camera movement. Add images for the subject and visual style, or audio for sound references.
Production guidance
Retrieve and save the video
- Submission returns a taskId. Use it to check progress, or set callback.url to receive a completion notification.
- Video URLs expire. Download any files you want to keep.
Best suited for
Subject and style references
Use reference images to keep a subject, product, wardrobe, or art direction consistent.
reference_image_urlsMotion and camera references
Use reference videos to guide action, timing, camera movement, and scene changes.
reference_video_urlsAudio references
Use reference audio to guide voice and sound style.
reference_audio_urlsRequest parameters
model string required Model ID.
input object required Prompt, reference media, and generation settings.
prompt string required Describe the scene, action, and camera movement you want. Use @video1, @image1, and @audio1 to refer to assets in the order they appear in each array.
reference_video_urls string[] required Reference videos that guide the action, camera movement, and scene. Provide publicly accessible HTTPS URLs.
- Formats
- Files
- 1-10 clipsUnder 200 MB each
- Duration / FPS
- 2-30 seconds each, up to 30 seconds combined24-60 fps
- Dimensions
- At least 409600 pixels, such as 854×480300-6000 px per side; aspect ratio 0.4-2.5
reference_image_urls string[] optional Reference images that guide the subject, composition, or visual style. Accepts HTTP(S) URLs and data URLs.
- Formats
- Files
- Up to 30 imagesUnder 30 MB each; up to 120 MB combined
- Dimensions
- 300-6000 px per sideAspect ratio 0.4-2.5
- Animated GIF
- Only the first frame is used
- Not supported
reference_audio_urls string[] optional Audio clips that guide the sound style. Use them together with a reference video.
- Formats
- Files
- Up to 10 clipsUnder 15 MB each
- Duration
- 2-30 seconds each, up to 30 seconds combined
resolution enum optional Output video resolution.
duration integer optional Length of the generated video, in seconds.
- Automatic
- Set -1 to let the model choose the duration
- Fixed length
- Set an integer from 4 to 30
aspect_ratio enum optional Output aspect ratio. adaptive selects a ratio from the prompt and reference media.
generate_audio boolean optional Generate synchronized dialogue, effects, and background audio.
output_format enum optional Output format. mp4 has broad compatibility; mov is intended for professional post-production.
web_search boolean optional Allow the model to search for current information mentioned in the prompt.
callback object optional Send a notification to your URL when the task succeeds or fails.
url string required HTTPS URL that receives the result notification.
when enum optional When to send the notification.
Example requests
Reference video with automatic duration
Replace the example URL with a publicly accessible reference video. Set duration=-1 to let the model choose the output length.
Request body
{
"model": "seedance-2.5/reference-to-video",
"input": {
"prompt": "Use @video1 as a reference for flowers gently moving in a light breeze. Preserve the natural colors and close-up composition. No text, logos, or people.",
"reference_video_urls": [
"https://example.com/reference-video.mp4"
],
"resolution": "480p",
"duration": -1,
"aspect_ratio": "16:9",
"generate_audio": false
}
}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"
}
}Motion and sound references
Use the action timing from a video and the sound style from an audio clip to create a new scene.
Request body
{
"model": "seedance-2.5/reference-to-video",
"input": {
"prompt": "Use the action timing of @video1 and the sound style of @audio1 to create a new shot in 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"
}
}Multiple camera references
Provide several videos and explain how each reference should guide the result.
Request body
{
"model": "seedance-2.5/reference-to-video",
"input": {
"prompt": "Combine the smooth tracking shot in @video1 with the orbiting camera in @video2 to create one continuous new 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
- Read data.taskId from the submission response.
- Call GET /v1/tasks/:id to check progress, or wait for a callback. Polling returns the task under data; callbacks contain the task result directly.
- When the status is success, find the video item in the output array and use its url to download the file.
FAQ
How do I enable automatic duration?
Set input.duration to -1. The model chooses the generated video length based on your prompt and reference media.
Can I provide only images or audio?
No. This endpoint requires at least one reference video. Images and audio are optional additions. For image-only input, use the image-to-video endpoint.
Will an image with invalid dimensions incur a charge?
No. An image that does not meet the dimension or aspect-ratio requirements returns HTTP 400. No task is created and no charge is made.