# seedance-2.0-fast/reference-to-video

> Seedance 2.0 Fast (Reference-to-Video) generates cinematic videos guided by up to 12 reference files spanning images, videos, and audio clips — optimized for faster generation at lower cost. Use @Image1, @Video1, @Audio1 tags in your prompt to assign roles for style transfer, motion transfer, and multi-scene composition. Supports 480P / 720P / 1080P / 4K output, 4-15s duration, and flexible aspect ratios. Ready-to-use REST inference API, best performance, no cold starts, affordable pricing.

- **Provider:** ByteDance
- **Category:** reference-to-video
- **Price:** $0.2210 (~~$0.2600~~) per run

## Key Features

- Multimodal reference inputs — combine up to 12 reference files (9 images + 3 videos + 3 audio clips) to orchestrate a unified video.
- @ mention syntax in prompts — use @image1, @video1, @audio1 tags to assign each reference asset a specific role with '= instruction' format.
- 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.
- Audio lip-sync — audio-driven mouth synchronization supporting 8+ languages.
- Faster generation — optimized for speed at 480p and 720p resolutions while retaining reference-to-video orchestration capabilities.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `prompt` | Yes | Scene description followed by @image1, @video1, @audio1 tags with '= instruction' to assign each asset a role (e.g. '@image1 = her: keep the exact face, she is the lead dancer'). |
| `image_urls` | No | Up to 9 reference image URLs for character, style, or scene guidance. |
| `video_urls` | No | Up to 3 reference video URLs (MP4/MOV, 480p-720p) for motion and camera guidance. |
| `audio_urls` | No | Up to 3 audio files (MP3/WAV, total ≤15s, each ≤15MB) for lip-sync or soundtrack. |
| `duration` | No | Video length in seconds: 4-15 (default: 5). |
| `aspect_ratio` | No | Output format: 16:9 (default), 9:16, 4:3, 3:4, 1:1, 21:9. |
| `resolution` | No | Output resolution: 480p or 720p (default). |
| `bitrate_mode` | No | Bitrate quality: standard (default) or high. |
| `generate_audio` | No | Generate synchronized audio (default: true). |
| `camera` | No | Camera movement: static, pan-left, pan-right, zoom-in, zoom-out, tilt-up, tilt-down. |
| `seed` | No | Random seed for reproducibility (-1 = random). |

## 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-15s), resolution (480p or 720p), aspect ratio, and camera movement.
4. Generate — submit and wait, then download the finished video with synchronized audio.
5. Iterate — use the fast generation speed to quickly test different reference combinations and prompts.

## Code Examples

### Python

```python
import os
import requests

response = requests.post(
    "https://aircube.ai/api/v3/seedance-2.0-fast/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": "720p",
    "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"])
```

### Node.js

```javascript
const response = await fetch("https://aircube.ai/api/v3/seedance-2.0-fast/reference-to-video", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.AIRCUBE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "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": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true
}),
});

const data = await response.json();

if (data.success) {
  console.log("ID:", data.data.id, "Status:", data.data.status);
} else {
  console.error("Error:", data.error.message);
}
```

### cURL

```curl
curl -X POST "https://aircube.ai/api/v3/seedance-2.0-fast/reference-to-video" \
  -H "Authorization: Bearer $AIRCUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true
}'
```

### Python (Async)

```python
import os
import time
import requests

# 1. Submit
response = requests.post(
    "https://aircube.ai/api/v3/seedance-2.0-fast/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": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
},
    timeout=300,
)
data = response.json()

if not data["success"]:
    print("Error:", data["error"]["message"])
    exit(1)

generation_id = data["data"]["id"]
print(f"Submitted: {generation_id}")

# 2. Poll until completed
while True:
    time.sleep(5)
    r = requests.get(
        f"https://aircube.ai/api/v3/status/{generation_id}",
        headers={"Authorization": "Bearer " + os.environ["AIRCUBE_API_KEY"]},
    )
    result = r.json()["data"]

    if result["status"] == "completed":
        print(result["output_url"])
        break
    elif result["status"] == "failed":
        print("Generation failed")
        break
```

### Node.js (Async)

```javascript
// 1. Submit
const response = await fetch("https://aircube.ai/api/v3/seedance-2.0-fast/reference-to-video", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.AIRCUBE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "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": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true
}),
});
const data = await response.json();

if (!data.success) {
  console.error("Error:", data.error.message);
  process.exit(1);
}

const generationId = data.data.id;
console.log("Submitted:", generationId);

// 2. Poll until completed
while (true) {
  await new Promise((r) => setTimeout(r, 5000));
  const res = await fetch(
    `https://aircube.ai/api/v3/status/${generationId}`,
    { headers: { "Authorization": "Bearer " + process.env.AIRCUBE_API_KEY } },
  );
  const result = (await res.json()).data;

  if (result.status === "completed") {
    console.log(result.output_url);
    break;
  } else if (result.status === "failed") {
    console.error("Generation failed");
    break;
  }
}
```

### cURL (Async)

```curl
# 1. Submit
RESPONSE=$(curl -s -X POST "https://aircube.ai/api/v3/seedance-2.0-fast/reference-to-video" \
  -H "Authorization: Bearer $AIRCUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true
}')

ID=$(echo "$RESPONSE" | jq -r '.data.id')
echo "Submitted: $ID"

# 2. Poll until completed
while true; do
  sleep 5
  STATUS_RES=$(curl -s "https://aircube.ai/api/v3/status/$ID" \
    -H "Authorization: Bearer $AIRCUBE_API_KEY")
  STATUS=$(echo "$STATUS_RES" | jq -r '.data.status')

  if [ "$STATUS" = "completed" ]; then
    echo "$STATUS_RES" | jq -r '.data.output_url'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Generation failed"; break
  fi
done
```

## Pricing

| Resolution | Duration | Cost |
| --- | --- | --- |
| 480p | 4s | $0.26 |
| 480p | 5s | $0.33 |
| 480p | 6s | $0.40 |
| 480p | 8s | $0.53 |
| 480p | 10s | $0.66 |
| 480p | 12s | $0.79 |
| 480p | 15s | $0.99 |
| 720p | 4s | $0.53 |
| 720p | 5s | $0.66 |
| 720p | 6s | $0.79 |
| 720p | 8s | $1.06 |
| 720p | 10s | $1.32 |
| 720p | 12s | $1.58 |
| 720p | 15s | $1.98 |

### Billing Rules

- 480p / 4s: $0.26.
- 720p / 4s: $0.53.
- Longer durations scale proportionally.
- 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 in 8+ languages.
- Multi-scene narrative — combine multiple references to maintain character, scene, and camera continuity across cuts.
- Rapid prototyping — quickly test reference combinations before rendering at higher quality with the standard model.

## 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.
- Use Fast for iteration and prototyping, then switch to the standard Seedance 2.0 for 1080p/4K final output.

## Notes

- Maximum 12 reference files per request (9 images + 3 videos + 3 audio clips).
- Total audio duration ≤15 seconds, each audio file ≤15MB.
- Available resolutions: 480p and 720p only (use standard Seedance 2.0 for 1080p/4K).
- Native audio generation is enabled by default.
- Duration range: 4-15 seconds (continuous selection).

## FAQ

**Q: What is the difference between Reference-to-Video and Image-to-Video?**

Image-to-Video animates a single image into motion. Reference-to-Video accepts up to 12 multimodal inputs (images, videos, audio) and orchestrates them into a unified video using @ mention syntax.

**Q: How does the @ mention syntax work?**

Write your scene description first, then use @image1, @video1, @audio1 with '= instruction' to tell the model how to use each asset. For example: '@image1 = her: keep the exact face and headdress, she is the lead dancer on the left'.

**Q: What is the difference between Seedance 2.0 Fast and the standard model?**

Fast generates quicker at 480p and 720p. The standard model supports up to 4K resolution and may produce higher-fidelity details.

**Q: Can I use audio only without images or video?**

No — audio references must be paired with at least one image or video reference.

**Q: How much does Seedance 2.0 Fast Reference-to-Video cost?**

Starting at $0.33 for a 480p 5-second clip, scaling with resolution and duration. The number of reference assets does not affect pricing.

**Q: Can I use outputs commercially?**

Yes — generated videos are yours to use. Check the Pricing page for plan-specific limits.