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

# Kling 4.0 API: Text, Keyframe & Reference Video

> Generate 3-30 second videos with Kling 4.0 on APIXO using text, keyframes, reference videos, named subjects, and voices at 720p or 1080p.

## Overview

Kling 4.0 creates videos from text, ordered keyframes, or reference materials. Use named subjects and voices to describe which materials should appear in the video.

| Capability | Value |
| - | - |
| Model ID | `kling-4-0` |
| Modes | `text-to-video`, `image-to-video`, `reference-to-video` |
| Prompt | Required in all modes; up to 8000 characters |
| Duration | Integer `3-30` seconds; default `5` |
| Resolution | `720p`, `1080p`; default `720p` |
| Keyframes | First frame, optional last frame, and up to 8 middle frames |
| References | Images, videos, named subjects, and voices |
| Output | Video URLs in the JSON string `data.resultJson` |

## Endpoint and authentication

Base URL: `https://api.apixo.ai/api/v1`.

| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/generateTask/kling-4-0` | Create a generation task |
| `GET` | `/statusTask/kling-4-0?taskId={taskId}` | Query status and retrieve results |

Use `Authorization: Bearer YOUR_API_KEY` on both endpoints. Send JSON requests with `Content-Type: application/json`.

## Copy-paste async quickstart

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/kling-4-0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-video",
      "prompt": "A cinematic city skyline at sunset, with a gentle camera move.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'
```

A successful submission returns a task ID. Save it for subsequent status requests.

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": { "taskId": "task_12345678" }
}
```

## Parameters

**request\_type** `string` (default: async)

Result delivery mode: `async` for polling or `callback` for webhook delivery.

**callback\_url** `string`

Required when `request_type=callback`. Use a public HTTPS endpoint that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks.md).

**input** `object` *required*

Kling 4.0 generation parameters.

**properties**

**mode** `string` *required*

`text-to-video`, `image-to-video`, or `reference-to-video`. Select a mode explicitly.

**prompt** `string` *required*

Non-empty video description, up to 8000 characters. Material mentions such as `@image_1` or `@Hero` must refer to materials declared in this request.

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

Output duration in seconds. Supports integers from `3` through `30`.

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

Output resolution: `720p` or `1080p`.

**aspect\_ratio** `string`

`auto`, `16:9`, `9:16`, `1:1`, or `21:9`. Defaults to `16:9` for text mode and `auto` for reference mode. Image mode follows the first frame's ratio and ignores this field.

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

Image mode requires 1-2 images: first frame, then optional last frame. Reference mode supports up to 10 reference images. Each image must have sides of 300-65536 pixels and a width/height ratio of 0.40-2.5.

**keyframe\_urls** `string[]`

Image mode only: up to 8 middle frames in chronological order. The total number of first, middle, and last frames must not exceed `min(10, duration + 1)`. Each image follows the same dimensions and ratio limits as `image_urls`.

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

Reference mode only: up to 5 reference videos, each 2-30 seconds. Together with videos in `elements`, there can be at most 5 input videos and 30 seconds of total input video duration.

**keep\_original\_sound** `boolean` (default: false)

Preserve the original reference video audio. Applies only when `video_urls` is provided; it does not toggle native audio generation. Native audio is generated when reference videos are absent.

**elements** `object[]`

Reference mode only: up to 7 named subjects, including at most 3 video subjects. Each subject requires a unique `name` and either 2-4 `image_urls` or one `video_url`. See Subject and voice parameters below.

**voices** `object[]`

Reference mode only: up to 3 named voices. Each object requires `name` and `audio_url`. Names must be unique across subjects and voices, ignoring case. See Subject and voice parameters below.

All media URLs must be publicly accessible HTTP(S) URLs and remain accessible while the task runs.

## Choose a mode and provide materials

### Text-to-video

Provide `mode=text-to-video` and a prompt. Reference materials are not used in this mode.

### Image-to-video with keyframes

The first `image_urls` entry is the first frame; a second entry is the last frame. Add chronological middle frames through `keyframe_urls`.

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "image-to-video",
    "prompt": "The camera leaves @first_frame, passes through @keyframe_1, and arrives at @last_frame.",
    "duration": 8,
    "resolution": "1080p",
    "image_urls": ["https://example.com/first.jpg", "https://example.com/last.jpg"],
    "keyframe_urls": ["https://example.com/middle.jpg"]
  }
}
```

### Reference-to-video

Provide at least one image, video, named subject, or voice. The four material arrays together cannot exceed 15 entries; one subject counts as one entry.

This request uses only a video subject. It uses the **with input video** price even though `video_urls` is absent.

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "reference-to-video",
    "prompt": "@Hero walks through a sunlit park and smiles at the camera.",
    "duration": 5,
    "resolution": "720p",
    "elements": [
      {"name": "Hero", "video_url": "https://example.com/hero.mp4", "tag": "character"}
    ]
  }
}
```

### Subject and voice parameters

| Subject field | Rules |
| - | - |
| `name` | Required; 1-20 Chinese characters, letters, digits, or underscores |
| `image_urls` | 2-4 subject views; the first is primary. Mutually exclusive with `video_url`. Each image follows the `image_urls` media limits |
| `video_url` | One continuous character shot lasting 3-8 seconds; shortest side at least 700 pixels. Mutually exclusive with `image_urls` |
| `tag` | Optional: `character`, `animal`, `prop`, `costume`, `scene`, `effect`, `others`. Video subjects only support `character` |
| `description` | Optional subject description, at most 100 characters |
| `voice_url` | Optional voice bound to a character subject; does not count toward the three standalone voices |

Each standalone voice has a required `name` and a publicly accessible `audio_url`. Voice names follow the same 1-20 character rules as subject names. Subject and voice names must be unique across the request, ignoring case. They cannot use reserved names such as `image_N`, `video_N`, `keyframe_N`, `object_N`, `audio_N`, `first_frame`, or `last_frame`.

If a character video has speech and no separate voice is bound, its speech may be used automatically.

### Mention materials in the prompt

| Material | Mention |
| - | - |
| Reference images | `@image_1`, `@image_2`, and so on |
| Reference videos | `@video_1`, `@video_2`, and so on |
| Named subject or voice | `@name`, using the declared name exactly |
| Keyframes | `@first_frame`, `@keyframe_1`, and optional `@last_frame` |

Every mention must match a declared material. If an ASCII name is followed by another ASCII letter, digit, or underscore, they are treated as part of the name: use a space or punctuation to end the mention. When declared names share a prefix, the longest matching name is used.

## Poll for result or receive a webhook

```bash theme={null}
curl "https://api.apixo.ai/api/v1/statusTask/kling-4-0?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Continue polling until `data.state` is `success` or `failed`. A successful video is returned as a JSON string in `data.resultJson`:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/video.mp4\"]}",
    "createTime": 1792713600000,
    "completeTime": 1792713780000,
    "costTime": 180000
  }
}
```

Parse `data.resultJson` with `JSON.parse()` and read `resultUrls`. Failed tasks return `failCode` and `failMsg`; HTTP `200` on a status query does not by itself indicate successful generation. Task timestamps use Unix milliseconds, and `costTime` is elapsed milliseconds.

For webhook delivery, set `request_type=callback` and provide `callback_url` when creating the task. The final payload follows the same task status structure. See [Webhooks](/docs/api-reference/webhooks.md).

## Billing

Prices are USD per **billable second**, with the same rates across modes for the same resolution and input video condition.

| Resolution | Without input video | With input video |
| - | -: | -: |
| `720p` | `$0.157` | `$0.094` |
| `1080p` | `$0.235` | `$0.141` |

Let `D` be output seconds and `V` the combined measured duration of all reference videos and video subjects.

* Without input video: billable seconds = `D`.
* With input video: billable seconds = `D + max(D, V)`.
* A video supplied only through `elements[].video_url` uses the with-video rate and contributes to `V`.
* Images and voice references do not add billable seconds.

For example, 720p with 10 output seconds and 5 input video seconds costs `20 × $0.094 = $1.88`. Reference-video quotes are estimates; final charges use measured input video durations, including fractional seconds. Do not round the reference duration to whole seconds when estimating charges.

See [Pricing](/docs/pricing.md) and [current API prices](https://apixo.ai/pricing/api).

## Latency and polling

Generation time varies by prompt, media inputs, output duration, resolution, and current workload. Longer clips can take several minutes.

| Workload | Typical generation time | Recommended first poll | Poll interval |
| - | - | - | - |
| Text, image, or reference generation | Varies with the request | 60s after task creation | 10s-15s |

Use webhook delivery for applications that do not need frequent status updates. Back off when requests are rate limited.

## Errors and troubleshooting

* Supply a non-empty `prompt` and a supported `mode` in every request.
* In image mode, provide 1-2 `image_urls` and keep the total frame count within the duration-dependent limit.
* In reference mode, declare at least one material, respect the combined video and material limits, and use only declared prompt mentions.
* If an input URL cannot be accessed, use a direct, publicly accessible media URL.
* On failure, check `failCode` and `failMsg` before submitting another task. See [Error Codes](/docs/api-reference/errors.md).

## Related links

* [Video Models](/docs/models/video)
* [Kling 3.0 Turbo](/docs/models/video/kling-3-0-turbo.md)
* [Kling 3.0 Omni](/docs/models/video/kling-3-0-omni.md)
* [Generate Task](/docs/api-reference/generate-task.md)
* [Status Task](/docs/api-reference/status-task.md)
* [Try Kling 4.0](https://apixo.ai/models/kling-4-0)


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