# kwaivgi/kling-v4.0/reference-to-video

> Kling V4.0 Reference-to-Video builds a new clip of 3 to 30 seconds from up to 10 reference images, 5 reference videos and 3 reference audios, following the subjects, motion and camera you point to in the prompt, with 720p and 1080p output and synchronized stereo audio. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

## Overview

- **Endpoint**: `https://api.wavespeed.ai/api/v3/kwaivgi/kling-v4.0/reference-to-video`
- **Polling/result URL**: `https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result`
- **Model ID**: `kwaivgi/kling-v4.0/reference-to-video`
- **Category**: reference-to-video

## Pricing

Without a reference video, the price is per second of output, and depends on the resolution and the duration you choose. The default request (720p, 5 s, no reference video) costs ~~$0.785~~ $0.66725 per run.

| Resolution | Per second (10 s duration) | 3 s duration | 5 s duration | 10 s duration | 30 s duration |
|---|---|---|---|---|---|
| 720p | ~~$0.157~~ $0.13345 | ~~$0.471~~ $0.40035 | ~~$0.785~~ $0.66725 | ~~$1.57~~ $1.3345 | ~~$4.71~~ $4.0035 |
| 1080p | ~~$0.235~~ $0.19975 | ~~$0.705~~ $0.59925 | ~~$1.175~~ $0.99875 | ~~$2.35~~ $1.9975 | ~~$7.05~~ $5.9925 |

With reference videos, the price is per second counted as the output length plus the longer of the output length and the total length of the reference videos (in whole seconds, up to 30). Reference audios are not charged. Prices for a 5 s output (duration 5), by total length of the reference videos:

| Total reference video length | 720p, 5 s duration | 1080p, 5 s duration |
|---|---|---|
| 5 s | ~~$0.94~~ $0.799 | ~~$1.41~~ $1.1985 |
| 10 s | ~~$1.41~~ $1.1985 | ~~$2.115~~ $1.79775 |
| 20 s | ~~$2.35~~ $1.9975 | ~~$3.525~~ $2.99625 |
| 30 s or more | ~~$3.29~~ $2.7965 | ~~$4.935~~ $4.19475 |

When the output is as long as the reference videos (10 s duration, 10 s of reference video):

| Resolution | Per output second (10 s duration, 10 s reference) | Whole request (10 s duration, 10 s reference) |
|---|---|---|
| 720p | ~~$0.188~~ $0.1598 | ~~$1.88~~ $1.598 |
| 1080p | ~~$0.282~~ $0.2397 | ~~$2.82~~ $2.397 |

---

## 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_):
  The positive prompt for the generation. Refer to reference images as @Image1, @Image2, ... (in array order), to reference videos as @Video1, @Video2, ... and to reference audios as @Audio1, @Audio2, ...

- **`images`** (`array of string`, _optional_):
  Reference images (up to 10).

- **`videos`** (`array of string`, _optional_):
  Reference videos (up to 5). They guide motion, camera and pacing; together they are used for up to 30 seconds.

- **`audios`** (`array of string`, _optional_):
  Reference audios (up to 3), 5-30 seconds each. They guide the voice and sound of the video.

- **`keep_original_sound`** (`boolean`, _optional_):
  Keep the reference video's own sound instead of generating new audio. Requires videos.
  - Default: `false`

- **`resolution`** (`string`, _optional_):
  Output resolution.
  - Default: `"720p"`
  - Options: "720p", "1080p"

- **`duration`** (`integer`, _optional_):
  The duration of the generated video in seconds (3-30).
  - Default: `5`
  - Options: 3, 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

- **`aspect_ratio`** (`string`, _optional_):
  The aspect ratio of the generated video; auto follows the reference images or video.
  - Default: `"auto"`
  - Options: "auto", "16:9", "9:16", "1:1", "21:9"



**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",
  "images": [],
  "videos": [],
  "audios": [],
  "keep_original_sound": false,
  "resolution": "720p",
  "duration": 5,
  "aspect_ratio": "auto"
}
```

### 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/kwaivgi/kling-v4.0/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/kwaivgi/kling-v4.0/reference-to-video)
- [API Documentation](https://wavespeed.ai/docs/docs-api/kwaivgi/kwaivgi-kling-v4.0-reference-to-video)
