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

# Kling video API

> Submit Kling text-to-video and image-to-video tasks, including v4 references. Poll native status, download results, and check limits and billed seconds.

Use Kling's text-to-video or image-to-video operation. Choose the generation version in `model_name`; the routing group binds the public billing model.

## Operations and limits

| Method | Path | Purpose |
| - | - | - |
| POST | `/kling/v1/videos/text2video` | Text to video |
| POST | `/kling/v1/videos/image2video` | Image to video |
| GET | `/kling/v1/videos/text2video/{task_id}` | Poll text-to-video tasks |
| GET | `/kling/v1/videos/image2video/{task_id}` | Poll image-to-video tasks |
| GET | `/v1/videos/{task_id}` | Compatible polling, when available |
| GET | `/v1/videos/{task_id}/content` | Download |

Use only operations available in [Model Square](https://floodgate.dev/models). Multi-image, Turbo, Omni, extension, motion-control, voice, avatar and asset APIs are separate, unreviewed contracts here.

| Public model / group | `model_name` | Duration | Mode and sound |
| - | - | - | - |
| `kling-video` / `Kling-2` | `kling-v2-5-turbo` | 5 or 10 seconds | `std` or `pro`, silent |
| `kling-video` / `Kling-2` | `kling-v2-6` | 5 or 10 seconds | `std` or `pro`; sound only with `pro` |
| `kling-video` / `Kling-2` | `kling-v3` | 3 to 15 seconds | `std` or `pro`, sound on or off |
| `kling-video-v4` / `Kling-3` | `kling-video-v4` | 3 to 30 seconds | `std` or `pro`; no separate sound selection |

Use a complete allowed configuration from the selected offering. Do not send the display model ID in a `model` field.

| Field | Required | Limits |
| - | - | - |
| `model_name`, `prompt`, `duration` | Yes | Prompt at most 2,500 characters; duration is an integer or integer string |
| `mode` | No | `std` or `pro`; default `std` |
| `sound` | No | Version-dependent `on`/`off`; legacy `false` means off. Omit for v4 or use off. |
| `aspect_ratio` | No | `16:9`, `9:16`, `1:1`; v4 also `21:9` |
| `image` | Image-to-video only, required | First frame |
| `image_tail` | Image-to-video only, optional | Last frame |
| `video_list[].video_url` | v4 only, optional | One HTTPS MP4/MOV reference, at most 100 MiB |

Frame images accept HTTPS URLs or raw base64 JPEG/PNG, at most 10 MiB per embedded image. Base64 data-URL prefixes and multipart uploads are unsupported. Text-to-video rejects frame images. Resolution is undocumented by this contract.

## Submit

```bash theme={null}
curl --fail-with-body https://api.floodgate.dev/kling/v1/videos/text2video \
  -H "Authorization: Bearer $FLOODGATE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model_name":"kling-v3","prompt":"A quiet forest beside a lake","mode":"std","duration":"5","sound":"off"}'
```

For image-to-video, use `/kling/v1/videos/image2video` and add `"image":"https://example.com/first-frame.png"`. Replace the URL with your accessible image.

```json theme={null}
{"code":0,"message":"success","data":{"task_id":"task_example","task_status":"submitted"}}
```

## Poll and download

Check `code: 0` and keep `data.task_id` as `TASK_ID`. Poll the same action used for submission:

```bash theme={null}
curl --fail-with-body "https://api.floodgate.dev/kling/v1/videos/text2video/$TASK_ID" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY"
```

For image-to-video tasks, use the corresponding `/image2video/$TASK_ID` path. Pending states are `submitted` and `processing`; terminal states are `succeed` and `failed`.

```json theme={null}
{"code":0,"message":"success","data":{"task_id":"task_example","task_status":"succeed","task_result":{"videos":[{"id":"asset_example","url":"/v1/videos/task_example/content","duration":"5"}]}}}
```

```json theme={null}
{"code":0,"message":"success","data":{"task_id":"task_example","task_status":"failed","task_status_msg":"Video generation failed"}}
```

Read results from `data.task_result.videos`. After `succeed`, download with authentication:

```bash theme={null}
curl --fail-with-body "https://api.floodgate.dev/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY" --output video.mp4
```

## Errors and billing

Inspect `code` even after HTTP 200 and `task_status_msg` on failure. Invalid version/mode/duration/sound combinations return `400`. Unfinished downloads return `400`, expired results `410`. Keep the original task after a timeout or `submission_uncertain`; see [shared video errors](https://docs.floodgate.dev/videos.md#errors-and-retries).

V2 uses the selected completed-request price. V3 uses verified output seconds. V4 bills requested output seconds plus the greater of rounded-up reference seconds and requested output seconds when a reference is present:

```text theme={null}
billed seconds = output seconds + max(ceil(reference seconds), output seconds)
```

Without a reference, v4 bills requested output seconds alone. A three-second output with a 3.041-second reference bills seven seconds. Total billed seconds must not exceed 3,600. Codec padding does not increase the output charge. Follow-ups retain the original group and price; confirmed failures release reservations, while missing final usage can leave settlement pending.


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