# Seedance 2.5 Reference to Video - Core.Today AI API

> ByteDance Seedance 2.5 reference-to-video via Fal.AI. Generates video from up to 50 multimodal references — up to 30 images, 10 videos, and 10 audio files — locking a character, set, and palette across a full 30-second take. Reference inputs are addressed from the prompt as @Image1, @Video1, @Audio1, and drive motion transfer, editing, extension, and lip-sync.

- **Provider**: ByteDance
- **Model ID**: bytedance/seedance-2.5/reference-to-video
- **Category**: Video Generation
- **Credits**: 5500 per 5s 720p video — billed per second (480p 513/s, 720p 1100/s; with reference videos 480p 615/s, 720p 1320/s)
- **Speed**: Medium
- **Quality**: Ultra

## Features
- Up to 50 reference files in one request — 30 images, 10 videos, 10 audio
- Prompt-level addressing (@Image1, @Video1, @Audio1) so each reference has an explicit role
- Character, wardrobe, and palette consistency across a full 30-second take
- Video editing and extension that preserve the original motion and camera work
- Audio-driven generation and lip-sync from reference audio

## Use Cases
- Outfit-change and try-on videos built from product stills plus a motion reference clip
- Multi-shot narratives that keep the same character across every cut
- Editing an existing clip — swapping a product or background while keeping the original camera move
- Extending an existing shot with consistent characters, environment, and style
- Music-synced or dialogue-synced content driven by reference audio

## API Endpoint

Base URL: https://api.core.today/v1
Create Prediction: POST /predictions
Get Status: GET /predictions/{job_id}

## Authentication
Header: X-API-Key: YOUR_API_KEY

## Input Parameters

### Required
- **prompt**: string - The text prompt used to generate the video. Address reference inputs as @Image1, @Video1, @Audio1, etc. For dialogue, put the spoken words in double quotes.
- **duration**: string - Duration of the video in seconds (4-30), sent as a string. Required — upstream also accepts "auto", but the resulting length is unknown at request time and cannot be billed accurately, so this gateway requires an explicit duration.
  Options: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30

### Optional
- **image_urls**: array - Reference images to guide video generation, addressed in the prompt as @Image1, @Image2, etc. Supported formats: JPG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF. Max 30 MB per image, up to 30 images. Total files across all modalities must not exceed 50.
- **video_urls**: array - Reference videos to guide video generation, addressed in the prompt as @Video1, @Video2, etc. Supported formats: MP4, MOV. Up to 10 videos; each 1.8-30.2s and at most 200 MB, combined duration at most 30.2s. Supplying any reference video switches billing to the video_in rate, which bills the reference footage as well as the output.
- **audio_urls**: array - Reference audio to guide video generation, addressed in the prompt as @Audio1, @Audio2, etc. Supported formats: MP3, WAV. Up to 10 files; each 1.8-30.2s and at most 15 MB, combined duration at most 30.2s. Requires at least one reference image or video.
- **resolution**: string (default: 720p) - Video resolution — 480p for faster generation, 720p for balance.
  Options: 480p, 720p
- **aspect_ratio**: string (default: auto) - The aspect ratio of the generated video. Use 16:9 for landscape, 9:16 for portrait/vertical, 1:1 for square, 21:9 for ultrawide cinematic, or auto to let the model decide.
  Options: auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
- **generate_audio**: boolean (default: true) - Whether to generate synchronized audio for the video, including sound effects, ambient sounds, and lip-synced speech. The cost of video generation is the same regardless of whether audio is generated.

## Examples

### Image references only
Reference images lock the subject and style; no reference video, so billing stays on the base per-second rate.
```json
{
  "model": "bytedance/seedance-2.5/reference-to-video",
  "input": {
    "prompt": "An octopus finds a football in the ocean and excitedly calls its octopus friends to come and play. Cut scene to an octopus football game under the sea.",
    "image_urls": [
      "https://v3b.fal.media/files/b/0a8eba37/Cqg-4Uwzyz4DELfceT1CF_a17e588773ec45b1a9e6f100a787b80b.jpg"
    ],
    "duration": "5",
    "resolution": "720p",
    "aspect_ratio": "auto",
    "generate_audio": true
  }
}
```

### Product swap inside an existing clip
Combine a reference video with a product image and describe what to change and what to keep. Reference videos are billed at the video_in rate.
```json
{
  "model": "bytedance/seedance-2.5/reference-to-video",
  "input": {
    "prompt": "Replace the perfume bottle in @Video1 with the face cream from @Image1, keeping all original motion and lighting.",
    "video_urls": [
      "https://example.com/original-shot.mp4"
    ],
    "image_urls": [
      "https://example.com/face-cream.jpg"
    ],
    "duration": "8",
    "resolution": "720p"
  }
}
```

## Response Format
```json
{
  "job_id": "abc123",
  "status": "pending | processing | completed | failed",
  "result": "URL or data (when completed)"
}
```

## Usage Flow
1. POST /predictions with model and input -> receive job_id
2. GET /predictions/{job_id} -> poll until status is completed or failed
3. Result contains output URL(s)

## Tips
- duration is a string on this endpoint — send "5", not 5. Integers are rejected before the request reaches the provider.
- Label every reference in the prompt (@Image1, @Video1, @Audio1). Unlabeled references get a vague role and the result drifts.
- Reference videos roughly double the per-second rate because the provider bills the reference footage as well as the output — use image references alone when you do not need motion transfer.
- For editing, say what to keep as explicitly as what to change: "...keeping all original motion and lighting."
- Reference audio requires at least one reference image or video; audio alone is rejected upstream.

## Documentation
https://fal.ai/models/bytedance/seedance-2.5/reference-to-video