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

# Kling V4 Video Generation

> Text-to-video, image-to-video, reference-based generation, video editing, and extension. Generate 3–30 seconds at 720p / 1080p, always with stereo audio.

> [!NOTE]
>
> This endpoint is asynchronous. After submission, use the returned `task_id` with `GET /v1/videos/generations/{task_id}` to query the task status and result.

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kling-v4",
    "prompt": "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "kling-v4",
        "prompt": "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "kling-v4",
    prompt: "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain",
    duration: 5,
    resolution: "720p",
    aspect_ratio: "9:16"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

## Mode selection

All five modes use the same model name, `kling-v4`. The mode is selected from the supplied assets and `omni_reference_task_type`.

| Mode | Input |
| - | - |
| Text-to-video | No image, video, or audio assets |
| Image-to-video | A first frame, optionally a last frame and up to 8 intermediate frames |
| Reference-based generation | Supply `video_urls`, `audio_urls`, or `reference_image` in `image_with_roles`; alternatively, explicitly set `omni_reference_task_type: "reference"` |
| Video editing | Set `omni_reference_task_type: "edit"` and supply an input video |
| Video extension | Set `omni_reference_task_type: "extend"` and supply an input video |

`omni_reference_task_type` defaults to `auto`, equivalent to omitting it. When explicitly set to `reference`, images in `image_urls` are treated as reference images.

> [!WARNING]
>
> Supplying only `video_url` without specifying `edit` or `extend` returns HTTP 400. To use a video as a reference asset, use `video_urls`.

## Request headers

**Authorization** `string` *required*

Bearer authentication: `Bearer <token>`, where `<token>` is your APIMart API Key.

## Request parameters

**model** `string` *required*

Must be `kling-v4`.

**prompt** `string`

Describe the content to generate or edit. Optional for image-to-video; required for all other modes.

In reference-based generation, use `@Image1`, `@Video1`, and `@Audio1` to refer to assets, numbered from 1 in each asset array. In video editing, the input video is `@Video1`, and reference images are `@Image1`, `@Image2`, and so on.

**duration** `integer`

Generated duration in seconds, from `3` to `30`; default: `5`.

* Video editing: when omitted, the output duration follows the input video.
* Video extension: the duration of the new segment. The returned video combines the original video and the new segment.

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

Output resolution: `720p` or `1080p`. Use this field to select the resolution; V4 does not support `mode`.

**aspect\_ratio** `string`

Supports `16:9`, `9:16`, `1:1`, and `21:9`. Reference-based generation also supports `auto`.

| Mode | Default behavior |
| - | - |
| Text-to-video | `16:9` |
| Image-to-video | Follows the first frame |
| Reference-based generation | `auto` |
| Video editing | Follows the input video |
| Video extension | This field is not supported; the original aspect ratio is preserved |

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

Image URL list, interpreted according to the mode:

* Image-to-video: the first image is the first frame and the second is the last frame; up to 2 images.
* Reference-based generation and video editing: up to 10 reference images. For generation using only reference images, explicitly set `omni_reference_task_type: "reference"`.

Asset URLs must be publicly accessible.

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

Image list with roles. Each item contains `url` and `role`.

| `role` | Purpose |
| - | - |
| `first_frame` | First frame for image-to-video; exactly 1 required |
| `last_frame` | Last frame for image-to-video, or target last frame for extension |
| `keyframe` | Intermediate frame for image-to-video; `middle_frame` is also accepted. Used in array order, up to 8 images |
| `reference_image` | Reference image for reference-based generation |

For image-to-video, the first frame, last frame, and intermediate frames must total no more than 10 images.

**first\_frame\_image** `string`

First-frame image URL for image-to-video. It can also be supplied as `first_frame` in `image_with_roles`, or as the first image in `image_urls`.

**last\_frame\_image** `string`

Last-frame image URL for image-to-video, or target last-frame image URL for extension.

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

Reference videos for reference-based generation: up to 5 clips, using no more than 30 seconds in total.

For video editing or extension, you may instead supply exactly 1 video URL in place of `video_url`, with `omni_reference_task_type: "edit"` or `"extend"`.

**video\_url** `string`

Input video URL for editing or extension. Requires `omni_reference_task_type: "edit"` or `"extend"`.

For editing, the input video must be at least 3 seconds; shorter videos return HTTP 400. Videos longer than 30 seconds are trimmed to the first 30 seconds.

**audio\_urls** `string[]`

Reference audio for reference-based generation: up to 3 clips, each 5–30 seconds long.

Reference images, videos, and audio combined must total no more than 15 assets for reference-based generation.

**omni\_reference\_task\_type** `string` (default: auto)

Supports `auto`, `reference`, `edit`, and `extend`.

* `auto`: selects text-to-video, image-to-video, or reference-based generation from the assets; equivalent to omitting the field.
* `reference`: reference-based generation; images in `image_urls` are treated as references.
* `edit`: video editing; requires an input video.
* `extend`: video extension; requires an input video.

**audio\_setting** `string`

Supports `origin` (preserve input video audio) and `auto` (generate new audio). Only for video editing or reference-based generation with reference videos.

* Video editing: preserves the original audio by default; `auto` generates new audio.
* Reference-based generation with reference videos: generates new audio by default; `origin` preserves reference video audio.
* Video extension: this field is not supported. Original audio is preserved, and audio is generated automatically for the new segment.

V4 always outputs video with stereo audio, generating sound together with the visuals.

## Request examples

Asset URLs below are placeholders. Replace them with real, publicly accessible URLs.

### Image-to-video: first and last frames

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "The camera slowly moves closer",
  "image_urls": ["https://example.com/start.png", "https://example.com/end.png"]
}
```

The first image is the first frame, and the second is the last frame. `prompt` is optional for image-to-video.

### Image-to-video: first, intermediate, and last frames

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "A girl walks from the window to the door, then looks back and smiles",
  "image_with_roles": [
    {"url": "https://example.com/1.png", "role": "first_frame"},
    {"url": "https://example.com/2.png", "role": "keyframe"},
    {"url": "https://example.com/3.png", "role": "keyframe"},
    {"url": "https://example.com/4.png", "role": "last_frame"}
  ],
  "duration": 10
}
```

Intermediate frames are used in array order. Exactly 1 first frame is required, with no more than 10 images across the first, last, and intermediate frames.

### Reference-based generation

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "The girl in @Image1 runs along the beach with the camera movement from @Video1 and background music from @Audio1",
  "image_with_roles": [
    {"url": "https://example.com/girl.png", "role": "reference_image"}
  ],
  "video_urls": ["https://example.com/camera.mp4"],
  "audio_urls": ["https://example.com/bgm.mp3"],
  "aspect_ratio": "auto",
  "duration": 5
}
```

Up to 10 reference images, 5 reference videos, and 3 reference audio clips, with no more than 15 assets combined. Reference videos use up to 30 seconds in total; each reference audio clip must be 5–30 seconds.

### Video editing

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "Change the scene to a snowy winter night",
  "omni_reference_task_type": "edit",
  "video_url": "https://example.com/in.mp4",
  "image_urls": ["https://example.com/style.png"]
}
```

The input video must be at least 3 seconds; videos longer than 30 seconds are trimmed to the first 30 seconds. If `duration` and `aspect_ratio` are omitted, the output follows the input video. Original audio is preserved by default; use `audio_setting: "auto"` to generate new audio.

### Video extension

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "The camera continues moving forward as the sky grows darker",
  "omni_reference_task_type": "extend",
  "video_url": "https://example.com/in.mp4",
  "duration": 5
}
```

Extension starts from the final frame of the input video. The result combines the original video and the new segment; only the new segment duration is billed.

Supply a target last frame with `last_frame_image` or `last_frame` in `image_with_roles`. Extension does not support `aspect_ratio` or `audio_setting`.

## Query a task

Replace the task ID in the following request with the ID returned on submission:

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/videos/generations/<task_id>' \
  --header 'Authorization: Bearer <token>'
```

Approximate generation time: 3 minutes for a 3-second 720p video, and 3.5 minutes for a 15-second video.

## Billing

Billed per second. See [Model Pricing](https://apimart.ai/pricing) for rates. `720p` and `1080p` are priced separately.

Video editing and reference-based generation with reference videos use the video-input rate. Other modes use the standard generation rate.

| Mode | Billable seconds |
| - | - |
| Text-to-video, image-to-video, reference-based generation with only images or audio | Output seconds |
| Video extension | New segment seconds |
| Video editing, reference-based generation with reference videos | Output seconds + max(output seconds, input video seconds) |

Input video seconds are calculated by summing clip durations, rounding up to a whole second, and capping at 30 seconds. For example, editing a 3.04-second video without `duration` produces 4 seconds, billed as 4 + 4 = 8 seconds.

For editing and reference-based generation with reference videos, input video duration is probed at submission. A probe failure returns HTTP 400 without charging. Failed generations receive a full refund.

## Unsupported parameters

The following parameters or values return HTTP 400:

* `mode`: V4 has no `std`, `pro`, or `4k` tiers. Use `resolution`.
* `negative_prompt`, `watermark: true`, `audio: false`.
* `multi_shot`, `multi_prompt`, `element_list`, `video_list`.
* `camera_control`, `voice_list`.

## Common errors

| Error | Action |
| - | - |
| `video_url needs omni_reference_task_type edit ... or extend` | Explicitly specify `edit` or `extend` when using `video_url`; use `video_urls` for reference videos |
| `image-to-video requires exactly 1 first frame` | Supply exactly 1 first frame; last or intermediate frames alone are not sufficient |
| `first frame, last frame and keyframes together are at most 10 images` | Reduce the total number of first, last, and intermediate frames to at most 10 |
| `reference images, videos and audios together are at most 15 files` | Reduce the total number of reference assets to at most 15 |
| `video edit requires an input video of at least 3 seconds` | Use an input video of at least 3 seconds |
| `Failed to probe the input video duration` | Check that the URL is accessible and points to a valid video file |
| `has no std/pro/4k mode` | Remove `mode` and use `resolution` |
| `Could not download the input from ... (HTTP 403)` | Use a publicly accessible asset URL without hotlink protection |


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