# Kling 4.0 Reference to Video API

> Generéiert 3-30 Sekonne laang Videoen, déi de Look vu bis zu 10 Referenzbiller, 5 Referenzvideoen a 7 Elementer bäibehalen

Erstellt e Video aus engem Text-`prompt` plus Referenzbiller, Referenzvideoen a Charakter- oder Objektelementer, déi am Prompt als @Image1, @Video1 oder @Element1 zitéiert ginn. D'Dauer reecht vun 3 bis 30 Sekonnen (Standard 5), mat enger Ausgab an 720p oder 1080p an den Aspektverhältnisser auto, 16:9, 9:16, 1:1 oder 21:9. Benotzt `multi_prompt` fir Prompte pro Shot; an deem Fall ass d'Gesamtlängt d'Zomm vun den Dauer vun de Shots. Limite si 10 Biller, 5 Videoe vun all Kéier 3-30s an 7 Elementer, vun deenen bis zu 3 eng Stëmm kënne mat sech féieren.

- Model id: `kling/v4/reference-to-video`
- Made by: Kling
- Category: Reference to Video
- Output: video
- Price per second of your output video: from $0.157 / second of output video (cheapest run $0.157 (157 API credits))
- Run: `POST https://api.doitong.com/v1/run/kling/v4/reference-to-video`
- Quote: `POST https://api.doitong.com/v1/quote/kling/v4/reference-to-video`
- Docs page: https://doitong.com/lb/developers/models/kling/v4/reference-to-video

## Pricing

Price: **from $0.157 / second of output video** (the lowest tier; the quote prices your exact input). Price per second of your output video: the input files are measured before the run (length, resolution, frame rate). The quote measures the same files and is exactly what the run charges.

Price by tier:

- 720p: $0.157 / second of output video
- 1080p: $0.235 / second of output video

The full example input below costs $1.175 = 1175 API credits (5 s output video × $0.235 (1080p)).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.com/v1/quote/kling/v4/reference-to-video` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `prompt` |  | string \| null | no |  | ≤ 2500 characters | Generatiounsinstruktiounen, déi d'Ufuerderung erfëllen, entweder `prompt` oder `multi_prompt` unzeginn. Fir geliwwert Inputen ze referenzéieren, benotzt @Image1, @Video1, @Element1 an esou weider. |
| `multi_prompt` |  | array of object {prompt, duration} \| null | no |  | ≥ 1 items | Generatiounsinstruktioune Shot fir Shot, wou all Prompt e Shot definéiert, deem seng Dauer zur Gesamtdauer vum Video bäidréit. |
| `multi_prompt[].prompt` |  | string | yes |  | 1 – 512 characters | Textinstruktioune fir den aktuelle Shot. |
| `multi_prompt[].duration` |  | integer | no | `5` | 1 – 30 | Dauer vun engem eenzele Shot, gemooss a Sekonnen. |
| `duration` |  | integer | no | `5` | 3 – 30 | Video-Längt a Sekonnen, vun 3 bis 30. |
| `start_image_url` | `image` | string (image URL) \| null | no |  |  | Optional Bild vum éischte Frame, dat op d'Limitt vun de Bildreferenze gerechent gëtt. Maximal Dateigréisst 30.0 MB; Breet an Héicht mussen all 300 px erreechen, mat engem Bildverhältnis tëscht 0.40 an 2.50. |
| `image_urls` | `images` | array of image URL \| null | no |  | ≤ 10 items | Bildreferenzen, mat @Image1, @Image2 an esou weider adresséiert, mat maximal 10 Biller. All Datei ass op 30.0 MB limitéiert, erfuerdert op d'mannst 300 px a béiden Dimensiounen a muss e Bildverhältnis tëscht 0.40 an 2.50 hunn. |
| `video_urls` | `videos` | array of video URL \| null | no |  | ≤ 5 items | Bis zu 5 Referenzvideoen, mat @Video1, @Video2 an esou weider adresséiert; all eenzel dauert 3–30 Sekonnen (maximal 30.05 Sekonnen), an hir Gesamtdauer zesumme mat den Elementvideoen däerf 30 Sekonnen net iwwerschreiden. All Datei däerf net méi wéi 300 MB hunn, mat Breet an Héicht tëscht 700 px an 4553 px. D'Bildverhältnis muss tëscht 0.40 an 2.50 leien, d'Frame-Rate tëscht 23.9 an 60.05 FPS. |
| `elements` |  | array of object {frontal_image_url, reference_image_urls, video_url, voice_id} \| null | no |  | ≤ 7 items | Sammlung vu bis zu 7 Personnagen oder Objeten, vun deenen héchstens 3 e `voice_id` kënnen enthalen an héchstens 3 e Video benotze kënnen. Adresséiert dës Elementer als @Element1, @Element2 an esou weider. |
| `elements[].frontal_image_url` |  | string (image URL) \| null | no |  |  | Frontalbild mat der Haaptusiicht vum Element. Maximal Dateigréisst 30.0 MB; béid Dimensioune mussen op d'mannst 300 px sinn, an d'Bildverhältnis muss tëscht 0.40 an 2.50 leien. |
| `elements[].reference_image_urls` |  | array of image URL \| null | no |  | ≤ 3 items | Zousazbiller aus verschiddene Wénkele vum Element, mat 1 bis 3 Usiichten. All Datei däerf héchstens 30.0 MB hunn, muss a béiden Dimensioune mindestens 300 px hunn an e Bildverhältnis tëscht 0.40 an 2.50 hunn. |
| `elements[].video_url` |  | string (video URL) \| null | no |  |  | Video-Duerstellung vun engem Element amplaz vu Biller, mat enger Dauer vun 3–30 Sekonnen (maximal 30.05 Sekonnen). D'Datei däerf net méi wéi 300 MB hunn; Breet an Héicht mussen tëscht 700–4553 px leien. Ënnerstëtzt Bildverhältnisser reeche vun 0.40–2.50, mat Frame-Raten vun 23.9–60.05 FPS. |
| `elements[].voice_id` |  | string \| null | no |  |  | Stëmm, déi dem Element zougewisen ass. |
| `resolution` |  | enum (string) | no | `1080p` | `720p`, `1080p` | Opléisung vum Output. |
| `aspect_ratio` |  | enum (string) | no | `16:9` | `auto`, `16:9`, `9:16`, `1:1`, `21:9` | Video-Proportiounen, explizitt ausgewielt oder aus de Referenze mat 'auto' ofgeleet. |

File parameters (`image`, `images`, `videos`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{}
```

A fuller example:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.com/v1/run/kling/v4/reference-to-video?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.com/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.com/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/kling/v4/reference-to-video?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.com/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/kling/v4/reference-to-video", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.com/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "kling/v4/reference-to-video",
      "input": {
        "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "kling/v4/reference-to-video",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 1175,
    "usd": "1.175",
    "charged": 1175,
    "refunded": 0
  },
  "input": {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field"
  },
  "output": {
    "video": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp4",
      "content_type": "video/mp4",
      "file_name": "0-output.mp4",
      "file_size": 1843200
    }
  },
  "outputs": [
    {
      "type": "video",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp4",
      "content_type": "video/mp4",
      "file_size": 1843200,
      "width": 1280,
      "height": 720,
      "duration": 5,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `video` | object {url, content_type, file_name, file_size} | Video, dee vum Modell produzéiert gëtt. |

## Related models

- [Kling 4.0 Text to Video](https://doitong.com/developers/models/kling/v4/text-to-video.md) (`kling/v4/text-to-video`): from $0.157 / second of output video
- [Seedance 2.0 Fast Reference to Video](https://doitong.com/developers/models/bytedance/seedance-2.0/fast/reference-to-video.md) (`bytedance/seedance-2.0/fast/reference-to-video`): from $0.113 / second
- [Seedance 2.0 Reference to Video](https://doitong.com/developers/models/bytedance/seedance-2.0/reference-to-video.md) (`bytedance/seedance-2.0/reference-to-video`): from $0.141 / second
- [Wan 3.0 Reference to Video](https://doitong.com/developers/models/alibaba/wan-3.0/reference-to-video.md) (`alibaba/wan-3.0/reference-to-video`): from $0.05 / second
- [Kling O1 Reference Image to Video \[Pro\]](https://doitong.com/developers/models/kling-video/o1/reference-to-video.md) (`kling-video/o1/reference-to-video`): $0.112 / second
- [Kling O1 Reference Image to Video \[Standard\]](https://doitong.com/developers/models/kling-video/o1/standard/reference-to-video.md) (`kling-video/o1/standard/reference-to-video`): $0.084 / second
- [Kling O3 Reference to Video \[Pro\]](https://doitong.com/developers/models/kling-video/o3/pro/reference-to-video.md) (`kling-video/o3/pro/reference-to-video`): from $0.112 / second
- [Kling O3 Reference to Video \[Standard\]](https://doitong.com/developers/models/kling-video/o3/standard/reference-to-video.md) (`kling-video/o3/standard/reference-to-video`): from $0.084 / second

## Links

- HTML page: https://doitong.com/developers/models/kling/v4/reference-to-video
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=kling/v4/reference-to-video
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.com/v1/models/kling/v4/reference-to-video