# Kling 4.0 Reference to Video API

> Menjana video 3-30 saat yang mengekalkan rupa sehingga 10 imej rujukan, 5 video rujukan dan 7 elemen

Mencipta video daripada `prompt` teks bersama imej rujukan, video rujukan serta elemen watak atau objek, yang dirujuk dalam prompt sebagai @Image1, @Video1 atau @Element1. Tempoh adalah dari 3 hingga 30 saat (lalai 5), dengan output pada 720p atau 1080p dan nisbah aspek auto, 16:9, 9:16, 1:1 atau 21:9. Gunakan `multi_prompt` untuk prompt bagi setiap syot, dalam hal ini jumlah panjang ialah hasil tambah tempoh setiap syot. Hadnya ialah 10 imej, 5 video selama 3-30s setiap satu dan 7 elemen, dengan sehingga 3 daripadanya boleh membawa suara.

- 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/ms/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 | Arahan penjanaan yang memenuhi keperluan untuk membekalkan sama ada `prompt` atau `multi_prompt`. Untuk merujuk input yang dibekalkan, gunakan @Image1, @Video1, @Element1 dan seterusnya. |
| `multi_prompt` |  | array of object {prompt, duration} \| null | no |  | ≥ 1 items | Arahan penjanaan mengikut syot, dengan setiap prompt mentakrifkan satu syot yang tempohnya menyumbang kepada jumlah panjang video. |
| `multi_prompt[].prompt` |  | string | yes |  | 1 – 512 characters | Arahan teks untuk syot semasa. |
| `multi_prompt[].duration` |  | integer | no | `5` | 1 – 30 | Tempoh syot individu, diukur dalam saat. |
| `duration` |  | integer | no | `5` | 3 – 30 | Panjang video dalam saat, daripada 3 hingga 30. |
| `start_image_url` | `image` | string (image URL) \| null | no |  |  | Imej bingkai pertama pilihan yang dikira dalam had imej rujukan. Saiz fail maksimum ialah 30.0 MB; lebar dan tinggi mestilah sekurang-kurangnya 300 px setiap satu, dengan nisbah aspek antara 0.40 dan 2.50. |
| `image_urls` | `images` | array of image URL \| null | no |  | ≤ 10 items | Imej rujukan yang dirujuk menggunakan @Image1, @Image2 dan seterusnya, dengan maksimum 10 imej. Setiap fail terhad kepada 30.0 MB, memerlukan sekurang-kurangnya 300 px pada kedua-dua dimensi, dan mesti mempunyai nisbah aspek antara 0.40 dan 2.50. |
| `video_urls` | `videos` | array of video URL \| null | no |  | ≤ 5 items | Sehingga 5 video rujukan, dirujuk menggunakan @Video1, @Video2 dan seterusnya; setiap satu berdurasi 3–30 saat (maksimum 30.05 saat), dan jumlah tempohnya bersama video elemen tidak boleh melebihi 30 saat. Setiap fail mestilah tidak melebihi 300 MB, dengan lebar dan tinggi masing-masing antara 700 px dan 4553 px. Nisbah aspek mestilah antara 0.40 dan 2.50, dan kadar bingkai antara 23.9 dan 60.05 FPS. |
| `elements` |  | array of object {frontal_image_url, reference_image_urls, video_url, voice_id} \| null | no |  | ≤ 7 items | Koleksi sehingga 7 watak atau objek, yang maksimum 3 daripadanya boleh menyertakan `voice_id` dan maksimum 3 boleh menggunakan video. Rujuk elemen ini sebagai @Element1, @Element2 dan seterusnya. |
| `elements[].frontal_image_url` |  | string (image URL) \| null | no |  |  | Imej menghadap hadapan yang menunjukkan paparan utama elemen. Saiz fail maksimum ialah 30.0 MB; kedua-dua dimensi mestilah sekurang-kurangnya 300 px, dan nisbah aspek mestilah antara 0.40 dan 2.50. |
| `elements[].reference_image_urls` |  | array of image URL \| null | no |  | ≤ 3 items | Imej tambahan yang menunjukkan sudut berbeza elemen, dengan 1 hingga 3 paparan. Setiap fail boleh berukuran maksimum 30.0 MB, mesti berukuran sekurang-kurangnya 300 px pada kedua-dua dimensi, dan mesti mempunyai nisbah aspek antara 0.40 dan 2.50. |
| `elements[].video_url` |  | string (video URL) \| null | no |  |  | Perwakilan video bagi elemen sebagai ganti imej, berdurasi 3–30 saat (maksimum 30.05 saat). Fail mestilah tidak melebihi 300 MB; lebar dan tinggi mestilah antara 700–4553 px. Nisbah aspek yang disokong ialah 0.40–2.50, dengan kadar bingkai 23.9–60.05 FPS. |
| `elements[].voice_id` |  | string \| null | no |  |  | Suara yang diberikan kepada elemen. |
| `resolution` |  | enum (string) | no | `1080p` | `720p`, `1080p` | Resolusi output. |
| `aspect_ratio` |  | enum (string) | no | `16:9` | `auto`, `16:9`, `9:16`, `1:1`, `21:9` | Perkadaran video, dipilih secara jelas atau diperoleh daripada rujukan dengan memilih '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 yang dihasilkan oleh 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