# Kling 4.0 Flash

> Kling 4.0 Flash API on PoYo. Generate fast 3–20 second 720p videos from text, a start frame, or image/video references and subjects, and edit source videos with references.

## Overview

- Submit: `https://api.poyo.ai/api/generate/submit`
- Status: `https://api.poyo.ai/api/generate/status/{task_id}`
- Page: https://poyo.ai/models/kling-4-0-flash
- Model page ID: `kling-4-0-flash`
- API model ID: `kling-4.0-flash`
- Category: Video
- Auth: `Authorization: Bearer $POYO_API_KEY`
- Create a key at https://poyo.ai/dashboard/api-key

This model uses PoYo's unified async API. POST the JSON body below, then poll status with the returned `task_id` or receive a webhook on `callback_url`. Failed tasks are not charged.

## Pricing

- 720p / No video input: 18.8 credits ($0.094) per second
- 720p / With video input: 12.6 credits ($0.063) per billed second

For more details, see https://poyo.ai/models/kling-4-0-flash.

## API Information

The request envelope is always `{ model, input, callback_url? }`. Input fields below are nested under `input`.

### Request envelope

- `model` (`ModelEnum`, required):
  Public model identifier.
  - Options: `"kling-4.0-flash"`
- `callback_url` (`string`, optional):
  Optional webhook URL for task completion or failure notifications.
  - Examples: "https://your-domain.com/callback"

### Input Schema

Selects editing when video_url is supplied, reference-to-video when reference images, reference videos, or subjects are supplied, image-to-video when only image_urls is supplied, and text-to-video otherwise. All media URLs must be publicly accessible HTTP or HTTPS URLs.

The API accepts the following `input` parameters:

- `prompt` (`string`, optional):
  Video instructions containing at least one non-whitespace character. Required in every mode except image-to-video, where it is optional. Reference images, videos, and subjects as @Image1, @Video1, and @Element1 in array order. In editing, the source video is @Video1 and reference videos start at @Video2. Existing @image_1 and @video_1 references remain supported.
  - Length: 1 to 26000 characters
  - Examples: "A paper boat drifts through a miniature city at sunset, slow camera push-in"
- `duration` (`integer`, optional):
  Output duration in whole seconds. Generation defaults to 5 seconds. In editing, omit this field to retain the source video duration; chargeable output duration is rounded up to whole seconds.
  - Range: `3` to `20`
  - Examples: `5`
- `resolution` (`ResolutionEnum`, optional):
  Output video resolution. Flash supports 720p only.
  - Default: `"720p"`
  - Options: `"720p"`
  - Examples: "720p"
- `aspect_ratio` (`AspectRatioEnum`, optional):
  Output aspect ratio for text and reference modes. Defaults to 16:9. In text-to-video, auto is treated as 16:9; in reference mode, auto adapts to the supplied materials. Do not provide this field in image or editing modes; those modes follow the aspect ratio of the starting frame or source video.
  - Default: `"16:9"`
  - Options: `"auto"`, `"16:9"`, `"9:16"`, `"1:1"`, `"21:9"`
  - Examples: "16:9"
- `reference_image_urls` (`list`, optional):
  Up to 10 publicly accessible HTTP or HTTPS reference images. Reference them as @Image1, @Image2, and so on. In reference mode, these images and the optional starting frame together cannot exceed 10 images. Supported in reference and editing modes.
  - Array of string
  - Length: 0 to 10
  - Examples: `["https://example.com/reference-image.png"]`
- `reference_video_urls` (`list`, optional):
  Publicly accessible HTTP or HTTPS reference videos, each lasting 3-20 seconds. Up to 5 in reference mode, referenced as @Video1, @Video2, and so on; up to 4 in editing mode, referenced as @Video2, @Video3, and so on. All input videos together must not exceed 20 seconds.
  - Array of string
  - Length: 0 to 5
  - Examples: `["https://example.com/reference-video.mp4"]`
- `image_urls` (`list`, optional):
  One publicly accessible HTTP or HTTPS starting frame. Flash does not accept an ending frame. Without references, selects image-to-video. In reference mode, the starting frame counts toward the 10-image and 15-material limits. Do not provide this field in editing mode.
  - Array of string
  - Length: 1 to 1
  - Examples: `["https://example.com/start-frame.png"]`
- `video_url` (`string`, optional):
  Publicly accessible HTTP or HTTPS source video for editing, lasting 3-20 seconds. Selects editing mode. Supports reference images, reference videos, and subjects; cannot be combined with image_urls or aspect_ratio.
  - Examples: "https://example.com/source.mp4"
- `kling_elements` (`list`, optional):
  Up to 7 position-based subjects. Use @Element1, @Element2, and so on in the prompt. At most 3 subjects may use videos. Supported in reference and editing modes. In reference mode, starting frames, reference images, reference videos, and subjects combined cannot exceed 15 materials; images inside a subject count as one subject.
  - Array of object
  - Length: 0 to 7
  - Examples: `[{"element_input_urls":["https://example.com/subject-front.png","https://example.com/subject-side.png"]}]`

Required Parameters Example:

```json
{
  "model": "kling-4.0-flash",
  "input": {
    "prompt": "A paper boat floats through a miniature city at sunset."
  }
}
```

Full Example:

```json
{
  "model": "kling-4.0-flash",
  "input": {
    "prompt": "A paper boat floats through a miniature city at sunset.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "reference_image_urls": [
      "https://example.com/reference-image.png"
    ],
    "reference_video_urls": [
      "https://example.com/reference-video.mp4"
    ],
    "image_urls": [
      "https://example.com/start-frame.png"
    ],
    "video_url": "https://example.com/source.mp4",
    "kling_elements": [
      {
        "element_input_urls": [
          "https://example.com/subject-front.png",
          "https://example.com/subject-side.png"
        ]
      }
    ]
  }
}
```

Animate a starting image:

```json
{
  "model": "kling-4.0-flash",
  "input": {
    "image_urls": [
      "https://example.com/start.png"
    ],
    "prompt": "The camera slowly pushes in as the lanterns flicker.",
    "duration": 10
  }
}
```

Guide the video with a reference image:

```json
{
  "model": "kling-4.0-flash",
  "input": {
    "prompt": "The character in @Image1 walks along a sunlit forest trail.",
    "reference_image_urls": [
      "https://example.com/character.png"
    ],
    "aspect_ratio": "9:16"
  }
}
```

### Output Schema

Submit returns a `task_id`. Poll `GET /api/generate/status/{task_id}` until `status` is `finished` or `failed`. Completed media is in `data.files`.

Response fields:

- `code` (`CodeEnum`, required):
  Business status code. `200` means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with `code: 400` in the body.
  
  - `200`: Success
  - `400`: Invalid request parameters
  - `401`: Missing or invalid API key
  - `402`: Insufficient credits
  - `403`: Permission denied
  - `404`: Resource not found
  - `408`: Request timeout
  - `429`: Rate limit exceeded
  - `500`: Internal server error
  - `502`: Upstream service error
  - `503`: Service unavailable
  
  See [Error Codes](/api-manual/error-codes) for details.
  - Options: `200`, `400`, `401`, `402`, `403`, `404`, `408`, `429`, `500`, `502`, `503`
  - Examples: `200`
- `data` (`object`, required):

Example Response:

```json
{
  "code": 200,
  "data": {
    "task_id": "task_example",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.poyo.ai/models/kling-4-0-flash/examples/kling-4-0-flash-default-output-1-39171475c864e959.mp4",
        "file_type": "video"
      }
    ]
  }
}
```

## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"kling-4.0-flash","input":{"prompt":"A paper boat floats through a miniature city at sunset."}}'
```

### Python

```python
import json
import os
import time
import requests

API = "https://api.poyo.ai"
headers = {
    "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
    "Content-Type": "application/json",
}
payload = json.loads("{\n  \"model\": \"kling-4.0-flash\",\n  \"input\": {\n    \"prompt\": \"A paper boat floats through a miniature city at sunset.\"\n  }\n}")

submit = requests.post(f"{API}/api/generate/submit", headers=headers, json=payload)
submit.raise_for_status()
task_id = submit.json()["data"]["task_id"]

while True:
    status = requests.get(f"{API}/api/generate/status/{task_id}", headers=headers)
    status.raise_for_status()
    data = status.json()["data"]
    if data["status"] in ("finished", "failed"):
        print(data)
        break
    time.sleep(2)
```

### JavaScript

```javascript
const headers = {
  Authorization: `Bearer ${process.env.POYO_API_KEY}`,
  "Content-Type": "application/json",
};

const submit = await fetch("https://api.poyo.ai/api/generate/submit", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "model": "kling-4.0-flash",
  "input": {
    "prompt": "A paper boat floats through a miniature city at sunset."
  }
}),
});

const submitted = await submit.json();
const taskId = submitted.data.task_id;

while (true) {
  const statusResponse = await fetch(`https://api.poyo.ai/api/generate/status/${taskId}`, { headers });
  const status = await statusResponse.json();
  if (["finished", "failed"].includes(status.data.status)) {
    console.log(status.data);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 2000));
}
```

## Additional Resources

### Documentation

- [Model Playground](https://poyo.ai/models/kling-4-0-flash)
- [API Documentation](https://docs.poyo.ai/api-manual/video-series/kling-4-0-flash)
- [API Documentation (Markdown)](https://docs.poyo.ai/api-manual/video-series/kling-4-0-flash.md)
- [Task status](https://docs.poyo.ai/api-manual/task-management/query-task-status)
- [Webhooks](https://docs.poyo.ai/api-manual/task-management/webhooks)

### Other agent-readable surfaces

- [Platform overview](https://poyo.ai/llms.txt)
- [Documentation index](https://docs.poyo.ai/llms.txt)
- [Full documentation text](https://docs.poyo.ai/llms-full.txt)
- Any other model: `https://poyo.ai/models/<model-id>/llms.txt`