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

> Text-to-video, a single starting image, image/video references, editing, and extension. 720p only, 3–20 generated seconds, 24fps.

> [!NOTE]
>
> This endpoint is asynchronous. After submission, use the returned `task_id` with `GET /v1/tasks/{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-flash",
    "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-flash",
        "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-flash",
    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-flash`. 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 | Exactly one first frame via `first_frame_image`, `first_frame` in `image_with_roles`, or the sole image in `image_urls` |
| Reference-based generation | Supply `video_urls` or `reference_image` in `image_with_roles`; alternatively set `omni_reference_task_type: "reference"` explicitly |
| 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-flash`.

**prompt** `string`

Describe the content to generate or edit. Optional for image-to-video; required otherwise. Use `@Image1` / `@Video1` for references, numbered from 1 in each array. For editing, the input video is `@Video1` and reference images are `@Image1`, `@Image2`, and so on.

**duration** `integer`

Integer seconds from `3` to `20`, normally defaulting to `5`. For editing, omission follows the input duration rounded up. For extension, this is the added segment length. Explicit `0` returns HTTP 400; `null` is equivalent to omission. Billing uses this integer duration; the actual file may be about one frame longer.

**seconds** `integer`

Alias for `duration`, with the same rules. If both are provided, each must be within `3`–`20` and their values must match; otherwise HTTP 400.

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

Only `720p`, the default when omitted. `1080p` returns HTTP 400. Selecting a tier with `mode` is not supported.

**aspect\_ratio** `string`

Text-to-video, reference generation, and editing support `16:9`, `9:16`, `1:1`, and `21:9`; only reference generation accepts `auto`. Image-to-video does not accept `aspect_ratio` or `size`: nonempty values return HTTP 400, while an empty string is treated as omitted. Crop the first frame beforehand to change the ratio.

| Mode | Default behavior |
| - | - |
| Text-to-video | `16:9` |
| Image-to-video | Do not send `aspect_ratio` / `size`; follows the first frame. Crop it first to change the ratio |
| 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-to-video accepts exactly one first frame; two images return HTTP 400. In reference generation and editing, these are reference images, up to 10. For image-only references, explicitly set `omni_reference_task_type: "reference"`. Asset URLs must be publicly accessible. First frames and reference images must be at least 300px wide and high, with a width-to-height ratio between 2:5 and 5:2. Invalid images return HTTP 400 at submission without charging.

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

Each item has `url` and `role`. Image-to-video accepts exactly one `first_frame`; reference generation and editing use `reference_image`. Last and intermediate frames are not supported. Up to 10 reference images and 15 assets total including reference videos. First frames and reference images must be at least 300px wide and high, with a width-to-height ratio between 2:5 and 5:2. Invalid images return HTTP 400 at submission without charging.

**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`. First frames and reference images must be at least 300px wide and high, with a width-to-height ratio between 2:5 and 5:2. Invalid images return HTTP 400 at submission without charging.

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

Up to 5 reference videos, no longer than 20 seconds in total. Exceeding the limit returns HTTP 400; clips are not trimmed. For editing or extension, exactly 1 entry may replace `video_url`, with the corresponding task type explicitly set.

Reference videos must be MP4 / MOV, with both width and height within 700–4553px. Duration is measured from the video stream, not the container: at least 3 seconds per clip and at most 20 seconds combined. Any reference clip shorter than 3 seconds returns HTTP 400 at submission without charging.

**video\_url** `string`

Input video URL for editing or extension. Requires explicit `omni_reference_task_type: "edit"` or `"extend"`; otherwise HTTP 400. Editing input must be 3–20 seconds. Shorter than 3 or longer than 20 seconds is rejected without charging.

Editing accepts MP4 / MOV videos with both width and height within 700–4553px. The 3–20-second limit uses video stream duration, not container duration. Invalid format, width, height, or editing duration returns HTTP 400 at submission without charging.

Extension inputs are not subject to the editing height range or its 3-second minimum; for example, a 480p, 2-second video can be extended.

**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`

For reference generation with video: `origin` preserves the first reference video’s audio; `auto` generates new audio and is the default. `origin` requires a reference video. If the first reference video has no audio track, the output has none either. Editing generates new audio and does not preserve the source audio; omit this parameter in editing requests. Extension does not accept it.

## Output dimensions and frame rate

Output uses the `720p` tier, with actual pixel dimensions varying by aspect ratio, at 24fps. The file may be about one frame longer than `duration`; for example, a 3-second request produces about 3.04 seconds.

| Aspect ratio / mode | Actual pixels |
| - | - |
| `16:9` | 1280×720 |
| `9:16` | 720×1280 |
| `1:1` | 960×960 |
| `21:9` | 1464×628 |
| Image-to-video | Follows the first frame, about 0.92MP total; a 1:2.5 first frame produces 604×1516 |

## Request examples

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

### Image-to-video: a single first frame

```json theme={null}
{
  "model": "kling-v4-flash",
  "image_urls": [
    "https://example.com/start.png"
  ]
}
```

Supply only one first frame; `prompt` is optional. Last frames, intermediate frames, and a second image are not supported.

Do not send `aspect_ratio` / `size`; follows the first frame. Crop it first to change the ratio.

First frames and reference images must be at least 300px wide and high, with a width-to-height ratio between 2:5 and 5:2. Invalid images return HTTP 400 at submission without charging.

### Reference-based generation

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

Up to 10 reference images and 5 reference videos, at most 15 assets combined. Reference videos must total no more than 20 seconds. Reference audio is not supported. Add `audio_setting: "origin"` to preserve the first reference video’s audio. With `origin`, a first reference video without an audio track produces output without an audio track.

First frames and reference images must be at least 300px wide and high, with a width-to-height ratio between 2:5 and 5:2. Invalid images return HTTP 400 at submission without charging.

Reference videos must be MP4 / MOV, with both width and height within 700–4553px. Duration is measured from the video stream, not the container: at least 3 seconds per clip and at most 20 seconds combined. Any reference clip shorter than 3 seconds returns HTTP 400 at submission without charging.

### Video editing

```json theme={null}
{
  "model": "kling-v4-flash",
  "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"
  ]
}
```

Editing input must have a video stream duration of 3–20 seconds. Without `duration`, output duration follows the input rounded up; without `aspect_ratio`, it follows the input ratio. Editing generates new audio and does not preserve source audio. Omit `audio_setting` in the request.

First frames and reference images must be at least 300px wide and high, with a width-to-height ratio between 2:5 and 5:2. Invalid images return HTTP 400 at submission without charging.

Editing accepts MP4 / MOV videos with both width and height within 700–4553px. The 3–20-second limit uses video stream duration, not container duration. Invalid format, width, height, or editing duration returns HTTP 400 at submission without charging.

### Video extension

```json theme={null}
{
  "model": "kling-v4-flash",
  "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
}
```

Generates a new 3–20-second segment from the input’s last frame and returns only that new segment, without the original video. Billing covers the new segment. Extension does not accept images, a target last frame, `aspect_ratio`, or `audio_setting`; the original ratio is preserved.

Extension inputs are not subject to the editing height range or its 3-second minimum; for example, a 480p, 2-second video can be extended.

## 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/tasks/<task_id>' \
  --header 'Authorization: Bearer <token>'
```

Use the [task status endpoint](https://docs.apimart.ai/en/api-reference/tasks/status.md). Save `task_id` and keep querying until `completed` or `failed`. A 3-second 720p video has taken about 1–4 minutes in testing; this is an estimate, not a fixed deadline for declaring failure.

## Billing

Billed per second; see [Model Pricing](https://apimart.ai/pricing) for rates. Standard generation and video-input modes use separate rates.

| Mode | Billable seconds |
| - | - |
| Text-to-video, image-to-video, image-only references | Output seconds; `kling-v4-flash@720P` |
| Video extension | Added segment seconds; `kling-v4-flash@720P` |
| Video editing, generation with reference videos | Output seconds + max(output seconds, input video seconds); `kling-v4-flash@720P-input` |

Input video seconds are the sum of video stream durations rounded up, not container durations. Editing a 3.04-second video with `duration: 3` is billed as 3 + 4 = 7 seconds. Editing and reference-video generation probe format, width, height, and video stream duration at submission. Probe failure, a format other than MP4 / MOV, width or height outside 700–4553px, a total over 20 seconds, or editing input shorter than 3 seconds returns HTTP 400 without charging. Each reference clip is measured by video stream duration; clips shorter than 3 seconds return HTTP 400 at submission without charging.

Failed tasks receive a full refund, including tasks the platform marks as timed out. Stopping client polling does not cancel a task; if it later succeeds, it is billed normally.

## Unsupported parameters

The following parameters or values return HTTP 400:

* `resolution: "1080p"`
* `last_frame_image`, `role: "last_frame"`, `role: "keyframe"`
* `audio_urls`, `audio_url`
* `mode`, `negative_prompt`, `watermark: true`, `audio: false`
* `multi_shot`, `multi_prompt`, `element_list`, `video_list`
* `camera_control`, `voice_list`

## Common errors

| Error | Action |
| - | - |
| `kling-v4-flash only supports resolution 720p (got: 1080p)` | Use `720p`, not `1080p`. |
| `kling-v4-flash duration must be between 3 and 20 seconds` | Use integer `duration` / `seconds` from 3 to 20; do not send 0. |
| `kling-v4-flash image-to-video follows the first frame's aspect ratio; remove aspect_ratio / size` | Remove `aspect_ratio` and `size` for image-to-video. The ratio follows the first frame; crop it beforehand to change the ratio. |
| `kling-v4-flash first frame: image width and height must be at least 300px` | First frames and reference images must be at least 300px on both axes. |
| `kling-v4-flash first frame: image aspect ratio (width:height) must be between 2:5 and 5:2` | Use an image width-to-height ratio between 2:5 and 5:2. |
| `kling-v4-flash input video #1: unsupported video format webm/mkv (supported: mp4/mov)` | Use MP4 / MOV for editing or reference videos; WebM / MKV are unsupported. |
| `kling-v4-flash input video #1: video height must be between 700 and 4553px` | Editing and reference videos require both width and height within 700–4553px. This range does not apply to extension inputs. |
| `kling-v4-flash input video #1: video width must be between 700 and 4553px` | Editing and reference videos require both width and height within 700–4553px. Portrait videos must also be at least 700px wide. |
| `kling-v4-flash reference video #1 must be at least 3 seconds` | Each reference clip must have a video stream duration of at least 3 seconds. Shorter clips return HTTP 400 at submission without charging. |
| `kling-v4-flash only supports aspect_ratio 16:9, 9:16, 1:1 or 21:9 (got: auto)` | Only reference generation supports `auto`; omit the ratio fields for image-to-video. |
| `kling-v4-flash image-to-video only takes a first frame; last frame and keyframes are not supported` | Keep one first frame; remove last/intermediate frames or the second image. |
| `kling-v4-flash reference-to-video does not take reference audios` | Remove `audio_urls` / `audio_url`. |
| `kling-v4-flash video extend takes no images` | Remove images and target last frames from extension requests. |
| `kling-v4-flash input videos must be at most 20 seconds in total` | Reference video totals or editing input must not exceed 20 seconds. No automatic trimming. |
| `video edit requires an input video of at least 3 seconds` | Use editing input with a video stream duration of at least 3 seconds, rather than relying on container duration. |
| `video_url needs omni_reference_task_type edit ... or extend` | Specify `edit` / `extend`; place reference videos in `video_urls`. |
| `Failed to probe the input video duration` | Check that the input URL is accessible and contains a valid video. |
| `duration (3) and seconds (5) are aliases and must match` | Send one alias, or make both values identical and within 3–20. |


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