seedance-2.5/reference-to-video

Key Features

• Up to 50 full-modal reference assets — combine images, videos and audio in a single request, the richest reference budget in the Seedance family.
• @ mention syntax in prompts — use @image1, @video1, @audio1 tags to assign each reference asset a specific role with '= instruction' format.
• Native 30-second clips — orchestrate longer, multi-scene sequences from a single reference set.
• Style transfer & character consistency — preserves facial features, clothing, and artistic style across frames and scenes without drift.
• Motion transfer — extracts choreography, action sequences, and camera movement from reference videos and applies them to new scenes.
• Native audio-visual synchronization — generates video with matched sound effects, dialogue, and ambient audio in a single pass.

Parameters

How to Use

1. Upload reference assets — images define appearance/style, videos define motion/camera, audio drives lip-sync/rhythm.
2. Write a prompt — describe the scene first, then use @image1 = instruction, @video1 = instruction to tell the model what to do with each asset (e.g. keep face, copy choreography).
3. Choose parameters — duration (4-30s), resolution (up to 1080p), aspect ratio, and camera movement.
4. Generate — submit and wait, then download the finished video with synchronized audio.
5. Iterate — start with 480p/5s for quick iterations, then render final output at 1080p.

Code Examples

import os
import requests

response = requests.post(
    "https://aircube.ai/api/v3/seedance-2.5/reference-to-video",
    headers={
        "Authorization": "Bearer " + os.environ["AIRCUBE_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
    "prompt": "A woman walks through a neon-lit alley at night, moody cinematic atmosphere.\n@image1 = her: keep the exact face and outfit, she walks through the alley\n@audio1 = use as the ambient background soundtrack",
    "image_urls": [
        "https://example.com/character.jpg"
    ],
    "audio_urls": [
        "https://example.com/ambient.mp3"
    ],
    "duration": 8,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
},
    timeout=300,
)
data = response.json()

if data["success"]:
    print("ID:", data["data"]["id"], "Status:", data["data"]["status"])
else:
    print("Error:", data["error"]["message"])

Pricing

Billing rules

• 480p / 4s: $0.76.
• 720p / 4s: $1.76.
• 1080p / 4s: $4.20.
• Longer durations scale proportionally.
• First 5 reference images are free; each additional image adds $0.04.
• Reference video input is billed per second at $0.12/s (480p), $0.26/s (720p), $0.63/s (1080p), added on top of the output price.
• Failed generations are not charged.

Best Use Cases

• Style transfer — apply a reference image's artistic style to generated video.
• Action / choreography cloning — extract motion from a reference video and apply it to new characters or scenes.
• Lip-sync — audio-driven mouth synchronization.
• Multi-scene narrative — combine up to 50 references to maintain character, scene, and camera continuity across a 30-second cut.
• Camera replication — extract dolly, tracking, or orbit camera techniques from a reference video.

Pro Tips

• With 1-2 images the model uses keyframe mode (faster); with 3+ assets or any video it switches to reference mode.
• Use the '@asset = instruction' format to assign each asset a clear role — e.g. '@image1 = her: keep the exact face and outfit, she is the lead dancer'.
• Use one primary camera instruction per prompt; add 'slow', 'smooth', or 'gentle' to control pacing.
• Audio references must be paired with at least one image or video.
• Take advantage of the 50-asset budget and 30-second ceiling for scenes with multiple characters or cuts.

Notes

• Up to 50 combined reference files per request (images + videos + audio).
• Native audio generation is enabled by default.
• Duration range: 4-30 seconds (continuous selection).
• Successor to Seedance 2.0 Reference-to-Video with a larger reference budget and longer duration ceiling.