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

# Kling 4.0 API

> Prepare text-to-video, keyframe and Omni requests for Kling 4.0.

[Try it](https://docs.gengen.farm/api-reference/kling/4.0/create-task.md) · [OpenAPI specification](https://docs.gengen.farm/openapi/kling-40-video.yaml)

Use model `kling-4.0` with the shared [create-task endpoint](https://docs.gengen.farm/api-reference/kling/4.0/create-task.md). Authenticate using a [GENGEN API key](https://docs.gengen.farm/authentication.md). Preview requests in [API Explorer](https://gengen.farm/api-explorer/demos/kling-40-video-generation).

## Workflows

All examples below use placeholder media URLs. Replace them with accessible HTTPS URLs before use. Images alone use the **no video input** billing tier.

### Text to video

```json theme={"dark"}
{
  "model": "kling-4.0",
  "mode": "text_to_video",
  "prompt": "Ocean waves at sunrise, with gentle surf sounds.",
  "controls": {
    "duration": 10,
    "resolution": "1080p",
    "watermark": false,
    "ratio": "16:9"
  }
}
```

### First frame

```json theme={"dark"}
{
  "model": "kling-4.0",
  "mode": "image_to_video",
  "prompt": "Animate @firstFrame1 with a slow camera push.",
  "assets": {
    "firstFrameImage": {
      "url": "https://example.com/firstFrame1.png",
      "id": "firstFrame1"
    }
  },
  "controls": {
    "duration": 10,
    "resolution": "1080p",
    "watermark": false
  }
}
```

### First and last frames

```json theme={"dark"}
{
  "model": "kling-4.0",
  "mode": "image_to_video",
  "prompt": "Transition smoothly from @firstFrame1 to @lastFrame1.",
  "assets": {
    "firstFrameImage": {
      "url": "https://example.com/firstFrame1.png",
      "id": "firstFrame1"
    },
    "lastFrameImage": {
      "url": "https://example.com/lastFrame1.png",
      "id": "lastFrame1"
    }
  },
  "controls": {
    "duration": 10,
    "resolution": "1080p",
    "watermark": false
  }
}
```

### Multiple keyframes

```json theme={"dark"}
{
  "model": "kling-4.0",
  "mode": "image_to_video",
  "prompt": "Move from @firstFrame1 through @middleFrame1 to @lastFrame1.",
  "assets": {
    "firstFrameImage": {
      "url": "https://example.com/firstFrame1.png",
      "id": "firstFrame1"
    },
    "middleFrameImages": [
      {
        "url": "https://example.com/middleFrame1.png",
        "id": "middleFrame1"
      }
    ],
    "lastFrameImage": {
      "url": "https://example.com/lastFrame1.png",
      "id": "lastFrame1"
    }
  },
  "controls": {
    "duration": 10,
    "resolution": "1080p",
    "watermark": false
  }
}
```

### Omni references

```json theme={"dark"}
{
  "model": "kling-4.0",
  "mode": "omni_video",
  "prompt": "Animate the character in @image1 using the motion of @video1.",
  "assets": {
    "referenceImages": [
      {
        "url": "https://example.com/image1.png",
        "id": "image1"
      }
    ],
    "referenceVideos": [
      {
        "url": "https://example.com/video1.mp4",
        "id": "video1"
      }
    ]
  },
  "controls": {
    "duration": 10,
    "resolution": "1080p",
    "watermark": false,
    "ratio": "adaptive"
  }
}
```

### Video editing

```json theme={"dark"}
{
  "model": "kling-4.0",
  "mode": "omni_video",
  "prompt": "Restyle @sourceVideo1 using the colors of @image1.",
  "assets": {
    "sourceVideo": {
      "url": "https://example.com/sourceVideo1.mp4",
      "id": "sourceVideo1"
    },
    "referenceImages": [
      {
        "url": "https://example.com/image1.png",
        "id": "image1"
      }
    ]
  },
  "controls": {
    "duration": 10,
    "resolution": "1080p",
    "watermark": false,
    "ratio": "adaptive"
  }
}
```

## Parameters and references

* `mode` is optional: reference images/videos, a source video, elements or voices select `omni_video`; keyframes select `image_to_video`; otherwise the mode is `text_to_video`.
* Output resolution is `720p` or `1080p` (default).
* `controls.duration` is an integer from 3 to 30. An explicit value takes precedence over the prompt. If omitted, the model follows the duration requested in the prompt; without a duration instruction, Omni uses the source video's duration when present, otherwise generation defaults to 10 seconds. The estimate/reservation still uses a maximum of 30 output seconds and final billing uses measured duration.
* Text-to-video accepts `21:9`, `16:9` (default), `9:16` or `1:1`. Omni also accepts `adaptive` (default). Omit `controls.ratio` for image-to-video; images determine it.
* In Omni, an explicit ratio takes precedence. With `adaptive`, the model follows the prompt's ratio instruction, then the source video, keyframe images, other input videos, and finally `16:9`. Among keyframes, the first frame takes precedence; without it, the first supplied keyframe is used.
* `controls.watermark` defaults to `false`; set it to `true` to return the watermarked video in `outputs.videos`. Describe audio requirements in `prompt`.
* Prompts must be nonblank. The mixed-language budget is ASCII code points / 26,000 + other Unicode code points / 11,000 ≤ 1.
* Media accepts an HTTPS URL string or `{ "url": "https://…", "id": "image1" }`. Reference the ID as `@image1` in the prompt. IDs contain letters, numbers, underscores or hyphens, are 1–128 characters, and must be unique across the task. Without an explicit ID, defaults are `firstFrame1`, `middleFrame1`, `lastFrame1`, `image1`, `video1` and `sourceVideo1` (array entries increment the suffix).
* Text-to-video uses the prompt alone. Image-to-video requires at least one keyframe. Omni can combine keyframes, reference images/videos and one source video.
* Use the documented request fields; omit `providerOptions` or pass an empty object.

Describe what each reference should contribute: for example, preserve the appearance of `@image1` while using only the movement from `@video1`. For editing, specify both what to change and what to preserve. Prompts can include positive and negative descriptions, event sequences, dialogue, ambient sound, music and sound effects.

## Media limits

| Input | Requirements |
| - | - |
| Images | JPEG/PNG, up to 30 MiB each, at least 300 pixels per side; aspect ratio from 2:5 through 5:2 |
| Videos | MP4/MOV, up to 300 MiB each, 3–30 seconds, 24–60 fps; 700–4553 pixels per side; at most 8,294,400 pixels; aspect ratio from 2:5 through 5:2 |
| Combined references | Up to 10 images, five video inputs, one source video, 15 total reference inputs; combined input-video duration at most 30 seconds |

Provide accessible HTTPS media URLs without embedded credentials.

Generated videos use 24 fps.

### Elements and voices

Use up to seven official preset elements in `assets.elements`, for example `{ "elementId": "official-preset-id", "id": "character1" }`. Up to three may be video elements. Their duration and count contribute to the video limits.

Use up to three voices from the [Kling voice directory](https://docs.gengen.farm/api-reference/kling/4.0/voices.md) in `assets.voices`. Each entry accepts a string `voiceId` and a unique reference `id` for use in the prompt. Elements and voices count toward the 15-reference total.

## Billing duration

Let **O** be measured output seconds and **I** be total input video seconds, including reference videos, the source video and video character elements.

| Inputs | Billable seconds | Price tier |
| - | - | - |
| No video input (including image-only workflows) | O | No video input, at the output resolution |
| Video input, I ≤ O | 2 × O | With video input, at the output resolution |
| Video input, I > O | I + O | With video input, at the output resolution |

The video-input formula is equivalently **O + max(I, O)**. Final charges use measured durations and the customer rate fixed at submission. Input duration cannot be omitted from an estimate when videos are present. See [pricing](https://docs.gengen.farm/pricing.md) for customer rates.

## Task lifecycle

Save the complete public `kling40:…` task ID and [retrieve the task](https://docs.gengen.farm/api-reference/kling/4.0/retrieve-task.md) with the owning GENGEN API key. States are `pending`, `processing`, `succeeded` and `failed`. Successful results expose the video in `outputs.videos` after storage and settlement. Download links expire; copy the video to your storage or retrieve the task again for a fresh link. Repeated queries do not repeat the generation charge.

After a timeout or uncertain response, query the existing task rather than submitting a replacement. If you have no task ID, contact support before retrying.


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