> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kling v3 Video Generation

> Generate videos with official Kling v3 using explicit reference-image and frame-role semantics

> [!NOTE]
>
> **Note for users in mainland China:** Please use `https://toapis.cn` as the API endpoint (Base URL). Replace `https://toapis.com` with `https://toapis.cn` in the examples in this document.

* Async task API, returns a task ID after submission
* Supports text-to-video, image-to-video, explicit first/last frame control, and audio video
* `mode=std` maps to 720P, `mode=pro` maps to 1080P
* `audio=true` generates an audio video and is billed as Sound
* `duration` supports `3s`, `4s`, `5s`, `6s`, `7s`, `8s`, `9s`, `10s`, `11s`, `12s`, `13s`, `14s`, `15s`

> [!WARNING]
>
> Use publicly accessible image URLs. Do not pass base64 image data. Upload local images with the [Upload Image API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) first.

## Authorization

**Authorization** `string` *required*

All endpoints require Bearer Token authentication.

```
Authorization: Bearer YOUR_API_KEY
```

## Request Parameters

**model** `string` *required*

Video generation model name, fixed as `kling-v3`.

**prompt** `string` *required*

Text prompt. Describe the subject, action, scene, camera movement, and style.

**mode** `string` (default: std)

Generation mode.

* `std` - standard mode, 720P
* `pro` - professional mode, 1080P

**duration** `integer` (default: 5)

Video duration in seconds.

Options: `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`

**aspect\_ratio** `string` (default: 16:9)

Video aspect ratio. Common values: `16:9`, `9:16`, `1:1`

**reference\_images** `string[]`

Normal reference images.

* These images are treated as references only
* They are **not** automatically converted into first/last frames
* Use `image_with_roles` for explicit frame control

**image\_with\_roles** `object[]`

Explicit image-role array for frame control and mixed inputs.

**Show image\_with\_roles object fields**

**url** `string` *required*

Publicly accessible image URL.

**role** `string` *required*

Image role.

Supported values:

* `first_frame`
* `last_frame`
* `reference`
* `reference_image`

> [!WARNING]
>
> `last_frame` is only sent when explicitly declared in `image_with_roles`. The system no longer infers the last frame from `reference_images[1]`.

**audio** `boolean` (default: false)

Whether to generate an audio video.

**metadata** `object`

Extended parameters.

**Show metadata fields**

**negative\_prompt** `string`

Negative prompt describing content to avoid.

**watermark** `boolean`

Whether to add watermark.

## Input Rules

| Input shape | Behavior |
| - | - |
| `reference_images` only | Normal references |
| `image_with_roles` with only `first_frame` / `last_frame` | Frame control |
| Both fields used together, or roles include both frame and reference semantics | Mixed mode |

## Examples

### Text-to-Video

```json theme={null}
{
  "model": "kling-v3",
  "prompt": "A golden cat running on a sunlit meadow, slow motion, cinematic quality",
  "mode": "std",
  "duration": 5,
  "aspect_ratio": "16:9"
}
```

### Image Reference

```json theme={null}
{
  "model": "kling-v3",
  "prompt": "Use the reference character and animate a subtle smile",
  "reference_images": ["https://example.com/reference.jpg"],
  "mode": "std",
  "duration": 5
}
```

### First and Last Frame Control

```json theme={null}
{
  "model": "kling-v3",
  "prompt": "The city naturally transitions from day to night",
  "image_with_roles": [
    { "url": "https://example.com/day.jpg", "role": "first_frame" },
    { "url": "https://example.com/night.jpg", "role": "last_frame" }
  ],
  "mode": "pro",
  "duration": 5
}
```

### Mixed Reference and Frame Input

```json theme={null}
{
  "model": "kling-v3",
  "prompt": "Keep the character identity consistent while transitioning scenes",
  "reference_images": ["https://example.com/character-reference.jpg"],
  "image_with_roles": [
    { "url": "https://example.com/start-scene.jpg", "role": "first_frame" },
    { "url": "https://example.com/end-scene.jpg", "role": "last_frame" }
  ],
  "mode": "pro",
  "duration": 5
}
```

### Audio Video

```json theme={null}
{
  "model": "kling-v3",
  "prompt": "A singer performing on stage, crowd cheering, flashing lights",
  "mode": "std",
  "duration": 5,
  "audio": true
}
```

> [!NOTE]
>
> Video generation is asynchronous. Use the [Get Video Task Status](https://docs.toapis.com/docs/en/api-reference/tasks/video-status.md) endpoint to query progress and results.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.