# bytedance/seedance-2.5/reference-to-video

> Seedance 2.5 Reference to Video creates cinematic videos with native audio from your own reference images, videos, and audio, keeping characters, products, motion, and sound consistent while a prompt directs the new shot. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

## Overview

- **Endpoint**: `https://api.wavespeed.ai/api/v3/bytedance/seedance-2.5/reference-to-video`
- **Polling/result URL**: `https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result`
- **Model ID**: `bytedance/seedance-2.5/reference-to-video`
- **Category**: reference-to-video

## Pricing

Pricing is calculated upfront using your selected `resolution` and `duration`, plus reference-video charges when applicable. A request with default settings (720p, 5 seconds, no reference videos) costs ~~$1.80~~ $1.62 per run.

### Without reference videos

Output-only pricing. The price scales with the requested `duration` and the chosen `resolution`. The "Per second" column is the rate for a `duration` of 10 seconds; the other columns are the total price for the stated `duration`.

| Resolution | Per second (`duration` = 10 s) | `duration` = 5 s | `duration` = 10 s | `duration` = 15 s | `duration` = 30 s |
|------------|-----------:|----------:|-----------:|-----------:|-----------:|
| 480p | ~~$0.18~~ $0.162 | ~~$0.90~~ $0.81 | ~~$1.80~~ $1.62 | ~~$2.70~~ $2.43 | ~~$5.40~~ $4.86 |
| 720p | ~~$0.36~~ $0.324 | ~~$1.80~~ $1.62 | ~~$3.60~~ $3.24 | ~~$5.40~~ $4.86 | ~~$10.80~~ $9.72 |
| 1080p | ~~$0.90~~ $0.81 | ~~$4.50~~ $4.05 | ~~$9.00~~ $8.10 | ~~$13.50~~ $12.15 | ~~$27.00~~ $24.30 |
| 4k | ~~$1.80~~ $1.62 | ~~$9.00~~ $8.10 | ~~$18.00~~ $16.20 | ~~$27.00~~ $24.30 | ~~$54.00~~ $48.60 |

Prices scale linearly with requested generation duration from 4 to 30 seconds.

### With reference videos

When reference videos are attached, you are charged for the normalized reference-video duration plus the requested generation `duration`, both at the same per-second rate for the chosen `resolution`. Each reference video is normalized to at least 2 seconds, each clip and the combined input are capped at 30 seconds, and the normalized combined input duration is rounded up to a whole second for billing.

The table shows the total price with a requested `duration` of 5 seconds, for different total reference-video lengths (`reference_videos` seconds).

| Resolution | Reference videos 5 s | Reference videos 10 s | Reference videos 20 s | Reference videos 30 s |
|------------|-----------:|-----------:|-----------:|-----------:|
| 480p | ~~$1.10~~ $0.99 | ~~$1.65~~ $1.485 | ~~$2.75~~ $2.475 | ~~$3.85~~ $3.465 |
| 720p | ~~$2.20~~ $1.98 | ~~$3.30~~ $2.97 | ~~$5.50~~ $4.95 | ~~$7.70~~ $6.93 |
| 1080p | ~~$5.50~~ $4.95 | ~~$8.25~~ $7.425 | ~~$13.75~~ $12.375 | ~~$19.25~~ $17.325 |
| 4k | ~~$11.00~~ $9.90 | ~~$16.50~~ $14.85 | ~~$27.50~~ $24.75 | ~~$38.50~~ $34.65 |

Example: 5 seconds of normalized reference input plus 5 seconds of output (`duration` = 5) costs ~~$1.10~~ $0.99 at 480p, ~~$2.20~~ $1.98 at 720p, ~~$5.50~~ $4.95 at 1080p, or ~~$11.00~~ $9.90 at 4k.

---

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
The API is asynchronous: submit a prediction, then poll its result URL until it completes.

### Input Schema

The API accepts the following input parameters:

- **`prompt`** (`string`, _required_):
  Describe the scene, action, camera movement, and mood for the video. Refer to reference media as @Image 1, @Video 1, @Audio 1 (in upload order) and say what each is for.

- **`reference_images`** (`array of string`, _optional_):
  Reference image URLs to keep characters, products, or scenes consistent and to guide style and composition. Provide at least one reference image, video, or audio; with none, the request runs as text-to-video.

- **`reference_videos`** (`array of string`, _optional_):
  Reference video URLs for motion, camera work, or a character to follow (total length must not exceed 30 seconds).

- **`reference_audios`** (`array of string`, _optional_):
  Reference audio URLs for voice, music, or sound style (total length must not exceed 30 seconds).

- **`aspect_ratio`** (`string`, _optional_):
  The aspect ratio of the generated video.
  - Default: `"16:9"`
  - Options: "16:9", "9:16", "4:3", "3:4", "1:1", "21:9"

- **`resolution`** (`string`, _optional_):
  The output video resolution.
  - Default: `"720p"`
  - Options: "480p", "720p", "1080p", "4k"

- **`duration`** (`integer`, _optional_):
  The duration of the generated video in seconds (4-30s).
  - Default: `5`
  - Range: `4` to `30`

- **`generate_audio`** (`boolean`, _optional_):
  Whether to generate native audio synchronized with the output video. Defaults to true.
  - Default: `true`

- **`output_format`** (`string`, _optional_):
  The container of the output video. mov is a QuickTime file with 4:4:4 video (H.264 up to 1080p, HEVC 10-bit at 4k) and uncompressed audio, intended for post-production; some browsers and players cannot play it.
  - Default: `"mp4"`
  - Options: "mp4", "mov"



**Required Parameters Example**:

```json
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
```

**Full Example**:

```json
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "reference_images": [],
  "reference_videos": [],
  "reference_audios": [],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "generate_audio": true,
  "output_format": "mp4"
}
```

### Result Data Schema

The `data` object returned by the API has the following fields:

- **`created_at`** (`string (date-time)`, _optional_):
  ISO timestamp of when the request was created (e.g., "2023-04-01T12:34:56.789Z").

- **`id`** (`string`, _optional_):
  Unique identifier for the prediction, the ID of the prediction to get.

- **`model`** (`string`, _optional_):
  Model ID used for the prediction.

- **`outputs`** (`array of string | object`, _optional_):
  Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.

- **`status`** (`string`, _optional_):
  Status of the task: created, processing, completed, or failed.

- **`urls`** (`object`, _optional_):
  Object containing related API endpoints.



**Example `data` Object**:

```json
{
  "created_at": "example",
  "id": "example",
  "model": "example",
  "outputs": [],
  "status": "example",
  "urls": {}
}
```

## Usage Examples

The examples use `jq` to read JSON. Set your API key first:

```bash
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
```

### 1. Submit a prediction

```bash
REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.wavespeed.ai/api/v3/bytedance/seedance-2.5/reference-to-video \
  --header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "${REQUEST_BODY}")

printf '%s\n' "${SUBMIT_RESPONSE}" | jq .
```

The response contains the prediction ID in `data.id`.

### 2. Poll until complete and read `outputs`

```bash
PREDICTION_ID=$(printf '%s' "${SUBMIT_RESPONSE}" | jq -r '.data.id')
if [ -z "${PREDICTION_ID}" ] || [ "${PREDICTION_ID}" = "null" ]; then
  printf 'Submission response did not contain data.id\n' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    --request GET \
    --url "${RESULT_URL}" \
    --header "Authorization: Bearer ${WAVESPEED_API_KEY}")

  RESULT=$(printf '%s' "${RESPONSE}" | jq -e '.data')
  STATUS=$(printf '%s' "${RESULT}" | jq -er '.status')
  case "${STATUS}" in
    completed)
      # Generated files are returned in the outputs array.
      printf '%s\n' "${RESULT}" | jq '.outputs'
      break
      ;;
    failed|cancelled|timeout|deleted)
      printf '%s\n' "${RESULT}" | jq '{status, error, code}'
      exit 1
      ;;
    *)
      sleep 2
      ;;
  esac
done
```

## Additional Resources

### Documentation

- [Model Playground](https://wavespeed.ai/models/bytedance/seedance-2.5/reference-to-video)
- [API Documentation](https://wavespeed.ai/docs/docs-api/bytedance/bytedance-seedance-2.5-reference-to-video)
