# Kling 4.0 Reference to Video API

> Generescha videos da 3-30 secundas che mantegnan l'apparientscha da fin a 10 maletgs da referenza, 5 videos da referenza e 7 elements

Crea in video a partir d'in `prompt` da text, plus maletgs da referenza, videos da referenza ed elements da persunas u objects, che vegnan citads en il prompt sco @Image1, @Video1 u @Element1. La durada varia da 3 fin 30 secundas (default 5), cun output en 720p u 1080p e proporziuns da l'ima auto, 16:9, 9:16, 1:1 u 21:9. Utilisescha `multi_prompt` per prompts per singulas scenas; en quest cas è la durada totala la summa da las duradas da las scenas. Ils limits èn 10 maletgs, 5 videos da 3-30s mintgin e 7 elements, dals quals fin a 3 pon cuntegnair ina vusch.

- 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/rm/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 | Instrucziuns da generaziun che ademplan il basegn da furnir u `prompt` u `multi_prompt`. Per far referenza a inputs furnids, utilisescha @Image1, @Video1, @Element1, e.u.v. |
| `multi_prompt` |  | array of object {prompt, duration} \| null | no |  | ≥ 1 items | Instrucziuns da generaziun plan per plan, cun mintga prompt che definescha in plan, la durada dal qual contribuescha a la durada totala dal video. |
| `multi_prompt[].prompt` |  | string | yes |  | 1 – 512 characters | Instrucziuns da text per il plan actual. |
| `multi_prompt[].duration` |  | integer | no | `5` | 1 – 30 | Durada d’in plan singul, mesirada en secundas. |
| `duration` |  | integer | no | `5` | 3 – 30 | Durada dal video en secundas, da 3 fin 30. |
| `start_image_url` | `image` | string (image URL) \| null | no |  |  | Maletg opziunal dal prim frame che vegn quintà envers la limita dals maletgs da referenza. La datoteca po avair maximalmain 30.0 MB; ladezza ed autezza ston avair mintgina 300 px, cun ina proporziun tranter 0.40 e 2.50. |
| `image_urls` | `images` | array of image URL \| null | no |  | ≤ 10 items | Referenzas da maletgs referenziadas cun @Image1, @Image2, e.u.v., cun maximalmain 10 maletgs. Mintga datoteca è limitada a 30.0 MB, dovra almain 300 px en omaduas dimensiuns e sto avair ina proporziun tranter 0.40 e 2.50. |
| `video_urls` | `videos` | array of video URL \| null | no |  | ≤ 5 items | Fin a 5 videos da referenza, referenziads cun @Video1, @Video2, e.u.v.; mintgin dura 3–30 secundas (maximalmain 30.05 secundas), e lur durada totala ensemen cun ils videos dals elements na dastga betg surpassar 30 secundas. Mintga datoteca sto esser pli pitschna che 300 MB, cun ladezza ed autezza mintgina tranter 700 px e 4553 px. La proporziun sto esser tranter 0.40 e 2.50, e la frequenza tranter 23.9 e 60.05 FPS. |
| `elements` |  | array of object {frontal_image_url, reference_image_urls, video_url, voice_id} \| null | no |  | ≤ 7 items | Collecziun da fin a 7 persunas u objects, dals quals maximalmain 3 pon cuntegnair in `voice_id` e maximalmain 3 pon utilisar video. Referenziescha quests elements sco @Element1, @Element2, e.u.v. |
| `elements[].frontal_image_url` |  | string (image URL) \| null | no |  |  | Maletg frontal che mussa la vista principala da l’element. La datoteca po avair maximalmain 30.0 MB; omaduas dimensiuns ston avair almain 300 px, e la proporziun sto esser tranter 0.40 e 2.50. |
| `elements[].reference_image_urls` |  | array of image URL \| null | no |  | ≤ 3 items | Maletgs supplementars che mussan differents anguls da l’element, cun 1 fin 3 vistas. Mintga datoteca po avair maximalmain 30.0 MB, sto mesirar almain 300 px en omaduas dimensiuns e sto avair ina proporziun tranter 0.40 e 2.50. |
| `elements[].video_url` |  | string (video URL) \| null | no |  |  | Rapresentaziun video d’in element empè da maletgs, cun ina durada da 3–30 secundas (maximalmain 30.05 secundas). La datoteca na dastga betg surpassar 300 MB; ladezza ed autezza ston esser tranter 700–4553 px. Las proporziuns sustegnidas èn 0.40–2.50, cun frequenzas da 23.9–60.05 FPS. |
| `elements[].voice_id` |  | string \| null | no |  |  | Vusch attribuida a l’element. |
| `resolution` |  | enum (string) | no | `1080p` | `720p`, `1080p` | Resoluziun da l’output. |
| `aspect_ratio` |  | enum (string) | no | `16:9` | `auto`, `16:9`, `9:16`, `1:1`, `21:9` | Proporziuns dal video, tschernidas explicitamain u deduidas da las referenzas cun la selecziun da 'auto'. |

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 producì dal model. |

## 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