> ## 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 v4 Video Generation

> One kling-4.0 model for text-to-video, reference media and first/middle/last keyframes

All three input modes use `kling-4.0`. The API selects the generation path from the supplied media. Generation is asynchronous; query the platform task ID returned by submission.

> [!NOTE]
>
> Use a platform API key. Mainland China users can replace `https://toapis.com` with `https://toapis.cn`. Availability depends on the deployed channel configuration and account access.

## Input modes

| Mode | Request content |
| - | - |
| Text-to-video | Send a prompt and output specifications without media. |
| Reference media | Use `image_urls` / `video_urls`, or media with reference roles. Images and videos can be combined. |
| Keyframes | Set `first_frame`, `keyframe` and `last_frame` explicitly in `image_with_roles`. Do not include reference images or videos. |

## Request parameters

**Authorization** `string` *required*

Authenticate with `Bearer YOUR_API_KEY`.

**model** `string` *required*

Always `kling-4.0`. Do not change the model ID between modes.

**prompt** `string` *required*

Required, nonblank, at most 8000 Unicode characters. Describe the subject, action, camera and relationships between media.

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

Integer from 3 to 30 seconds. Defaults to 5.

**resolution** `string` (default: 720p)

`720p` or `1080p`. Defaults to `720p`. Select resolution with this field.

**aspect\_ratio** `string`

`auto`, `16:9`, `9:16`, `1:1` or `21:9`. Omission leaves the upstream default unchanged; send `auto` explicitly for automatic aspect ratio.

**image\_urls** `string[]`

Reference image URL array, at most 10 images. Positions do not imply first/last frames. Counts combine with reference image roles; use one representation per media item.

**video\_urls** `string[]`

Reference video URL array, at most 5 videos combined with `video_with_roles`.

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

Each object has `url` and `role`. `reference` / `reference_image` means reference image; `first_frame`, `keyframe` and `last_frame` mean first, middle and last frames.

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

Each object has `url` and `role`. Supported roles: `reference` / `reference_video`.

**metadata** `object`

Boolean `keep_original_sound` preserves reference video audio, for example `{"keep_original_sound": true}`. Use for reference videos only. Keyframe mode rejects this key even when false.

**client\_business\_id** `string`

Optional client business ID, stored with the task and accepted by the same query endpoint.

## Media rules and validation

* Use publicly accessible HTTP(S) media URLs without usernames or passwords. Upload local files with [image upload](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) or [video upload](https://docs.toapis.com/docs/en/api-reference/uploads/videos.md). Do not send local paths or base64.
* Reference mode allows up to 10 images and 5 videos. Plain arrays and explicit reference roles are combined; do not send the same media twice.
* Keyframe mode requires at least one image. At most one first frame, one last frame and 8 middle frames; total at most `min(duration + 1, 10)`. Examples: 3 seconds permits 4 frames, 5 permits 6, and 9-30 permits 10.
* Middle frames follow the order of `keyframe` items in the array. First and last frames are selected by role, not plain image positions. A first frame alone, last frame alone or middle frames alone also select keyframe mode.
* Keyframes and reference media are mutually exclusive. Do not use legacy Kling `mode`, `audio`, `video_list` or Omni reference structures. `audio_with_roles`, `metadata.elements` and `metadata.voices` are unsupported.
* Invalid specifications, roles, URLs, counts or mode combinations are rejected. Correct the returned error before retrying. This page does not promise file size, codec or input video duration limits; media must also satisfy upload service and upstream requirements.

## Request examples

### Text-to-video

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "Waves on the shore, a slow camera push, sunset lighting",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

### Reference media

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "Keep the character from the reference image and the camera motion from the reference video",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/motion.mp4"
  ],
  "metadata": {
    "keep_original_sound": true
  }
}
```

### Keyframes

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "Transition smoothly from the first frame through the middle scene to the last frame",
  "duration": 5,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_with_roles": [
    {
      "url": "https://example.com/first.png",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/middle-1.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/middle-2.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/last.png",
      "role": "last_frame"
    }
  ]
}
```

### Submit a task

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "prompt": "Waves on the shore, a slow camera push, sunset lighting",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'
```

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "model": "kling-4.0",
  "status": "queued",
  "created_at": 1792713600
}
```

## Task queries and billing

The response `id` is the platform task ID. Query it below instead of using the provider task\_id. States include `queued`, `in_progress`, `completed` and `failed`. See [video task status](https://docs.toapis.com/docs/en/api-reference/tasks/video-status.md) for the result schema and [task webhooks](https://docs.toapis.com/docs/en/api-reference/webhooks/task-webhooks.md) for callbacks.

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/videos/generations/YOUR_TASK_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

Defaults are 5 seconds / 720p. Set these explicitly to control output specifications. This page does not quote fixed prices or equate original audio preservation with legacy Sound billing. Account quotes and task usage / billing determine the actual charges.


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