---
title: "Kling AI Text-to-Video API Reference"
aliases: [kling-api, kling-t2v, kling-video-api]
tags: [kling, ai-video, api, text-to-video, video-generation]
sources: [raw/Kling AI Next-Gen AI Video & AI Image Generator 1.md]
created: 2026-04-26
updated: 2026-04-26
---

## Overview

Kling AI provides a REST API for AI video generation from text prompts. Base URL: `https://api-singapore.klingai.com`. Auth via Bearer token in the `Authorization` header.

Used in the [[wiki/web-agency/claude-code-nanobanana-website-workflow|Claude Code + Nanobanana 2 Website Workflow]] for animating hero images.

---

## Create Task — `POST /v1/videos/text2video`

### Key Parameters

| Parameter | Type | Notes |
|-----------|------|-------|
| `model_name` | string | `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3` |
| `prompt` | string | Max 2500 chars. Use `<<<image_1>>>` syntax for Omni model references |
| `negative_prompt` | string | What to avoid |
| `mode` | enum | `std` (720p), `pro` (1080p), `4k` |
| `duration` | enum | 3–15 seconds |
| `aspect_ratio` | enum | `16:9`, `9:16`, `1:1` |
| `sound` | enum | `on` / `off` |
| `cfg_scale` | float | `[0,1]` — lower = more creative. Not supported on kling-v2.x |
| `multi_shot` | bool | Enable multi-scene storyboard mode |
| `callback_url` | string | Webhook called on task status change |
| `external_task_id` | string | Your own ID (unique per account, queryable) |

### Minimal Example

```bash
curl -X POST https://api-singapore.klingai.com/v1/videos/text2video \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model_name": "kling-v2-6",
    "prompt": "A cute rabbit reading a newspaper, cappuccino on the table",
    "duration": "5",
    "mode": "pro",
    "sound": "on",
    "aspect_ratio": "1:1"
  }'
```

### Response

```json
{
  "code": 0,
  "data": {
    "task_id": "string",
    "task_status": "submitted",
    "created_at": 1722769557708
  }
}
```

Task statuses: `submitted` → `processing` → `succeed` / `failed`

---

## Multi-Shot (Storyboard) Mode

Set `multi_shot: true` + `shot_type: "customize"` to define up to 6 scenes independently:

```json
{
  "model_name": "kling-v3",
  "multi_shot": true,
  "shot_type": "customize",
  "duration": "15",
  "multi_prompt": [
    { "index": 1, "prompt": "Two friends under a streetlight", "duration": "2" },
    { "index": 2, "prompt": "Runner sprinting through forest", "duration": "3" },
    { "index": 6, "prompt": "Sunset over mountains", "duration": "1" }
  ],
  "mode": "pro",
  "sound": "on",
  "aspect_ratio": "9:16"
}
```

- `shot_type: "intelligence"` — model auto-splits the single prompt into scenes
- `shot_type: "customize"` — you define each scene via `multi_prompt`
- Sum of storyboard durations must equal total `duration`
- Max 512 chars per storyboard prompt; max 6 storyboards

---

## Camera Control

Optional `camera_control` object to drive camera movement:

```json
"camera_control": {
  "type": "simple",
  "config": { "zoom": 5 }
}
```

**Predefined types:** `simple`, `down_back`, `forward_up`, `right_turn_forward`, `left_turn_forward`

For `simple`, set exactly one of: `horizontal`, `vertical`, `pan`, `tilt`, `roll`, `zoom` (range `[-10, 10]`). Others must be `0`.

---

## Query Task

### Single — `GET /v1/videos/text2video/{task_id}`

```bash
curl https://api-singapore.klingai.com/v1/videos/text2video/{task_id} \
  -H 'Authorization: Bearer <token>'
```

Response includes `task_result.videos[].url` — **videos expire after 30 days, save promptly.**

### List — `GET /v1/videos/text2video?pageNum=1&pageSize=30`

Pagination: `pageNum` `[1–1000]`, `pageSize` `[1–500]`.

---

## Watermark

```json
"watermark_info": { "enabled": true }
```

Response includes both `url` (clean) and `watermark_url` when enabled. Custom watermarks not supported.

---

## Key Takeaways

- **Model field renamed:** use `model_name` (not `model`). Old `model` still works but defaults to v1.
- **Async flow:** create task → poll or use `callback_url` for status.
- **Video URLs expire in 30 days** — download immediately after generation.
- **Multi-shot** lets you build a 15-second video from 6 independent scenes with `kling-v3`.
- **Omni model** (`kling-v3`) accepts image/video/element references in prompt via `<<<image_1>>>` syntax.
- `cfg_scale` not supported on v2.x models.
- `sound: "on"` enables auto-generated audio; add `<<<voice_1>>>` in prompt to specify a voice.

---

## Related

- [[wiki/web-agency/claude-code-nanobanana-website-workflow|Claude Code + Nanobanana 2 Website Workflow]] — Kling used for hero video animation
- [[wiki/llm-models/_index|LLM Models]] — model catalog patterns (parallel to Kling's model versioning)

---

## Sources

- Raw: `Kling AI Next-Gen AI Video & AI Image Generator 1.md`
