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

# Kling 3.0 Turbo 视频生成 API | 官方协议

> 可灵 3.0 Turbo 视频生成，支持文生视频与图生视频（仅首帧），分辨率 720p/1080p，时长 3–15 秒，官方 Turbo 协议接入。

通过 即刻API 统一网关调用可灵 3.0 Turbo 视频生成接口，使用官方 Kling Turbo 上游协议，支持文生视频和图生视频（仅支持首帧），所有任务均为异步处理。

<Warning>
  * 图生视频仅支持首帧，`reference_images` 中只有第一张图片会被用作首帧
  * 当前接入**不支持尾帧**，多余图片不会传给上游
  * `aspect_ratio` 仅对文生视频生效
</Warning>

## 请求参数

<ParamField body="model" type="string" required>
  视频生成模型名称，固定为 `kling-3.0-turbo`。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频提示词。对于图生视频，该字段会转换为 Kling Turbo `contents` 中的 `prompt` 项。
</ParamField>

<ParamField body="reference_images" type="string[]">
  可选输入图片 URL 数组。Kling Turbo 图生视频只会取第一张图作为首帧。
</ParamField>

<ParamField body="resolution" default="720p" type="string">
  视频分辨率。支持值：

  * `720p` — 默认
  * `1080p`
</ParamField>

<ParamField body="duration" default="5" type="integer">
  视频时长，单位秒。支持值：`3`、`4`、`5`、`6`、`7`、`8`、`9`、`10`、`11`、`12`、`13`、`14`、`15`。
</ParamField>

<ParamField body="aspect_ratio" default="16:9" type="string">
  文生视频宽高比（图生视频中此参数无效）。支持值：

  * `16:9`（默认）
  * `9:16`
  * `1:1`
</ParamField>

<ParamField body="watermark" default="false" type="boolean">
  是否添加官方 Kling 水印。
</ParamField>

## 请求示例

<CodeGroup>
  ```bash cURL（文生视频） theme={null}
  curl --request POST \
    --url https://geekapis.com/v1/videos/generations \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "kling-3.0-turbo",
      "prompt": "A cinematic shot of a red sports car driving through rain",
      "resolution": "720p",
      "duration": 5,
      "aspect_ratio": "16:9"
    }'
  ```

  ```bash cURL（图生视频） theme={null}
  curl --request POST \
    --url https://geekapis.com/v1/videos/generations \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "kling-3.0-turbo",
      "prompt": "Animate the character with subtle camera motion",
      "reference_images": ["https://example.com/first-frame.png"],
      "resolution": "1080p",
      "duration": 5,
      "watermark": true
    }'
  ```
</CodeGroup>

## 返回示例

```json 200 theme={null}
{
  "id": "video_01K8SGYNNNVBQTXNR4MM964S7K",
  "object": "generation.task",
  "model": "kling-3.0-turbo",
  "status": "queued",
  "progress": 0,
  "created_at": 1768380224,
  "metadata": {}
}
```

## 响应字段

| 字段           | 类型      | 说明                                                     |
| ------------ | ------- | ------------------------------------------------------ |
| `id`         | string  | 任务唯一标识符，用于查询任务状态                                       |
| `object`     | string  | 对象类型，固定为 `generation.task`                             |
| `model`      | string  | 使用的模型名称                                                |
| `status`     | string  | 任务状态：`queued` / `in_progress` / `completed` / `failed` |
| `progress`   | integer | 任务进度百分比（0–100）                                         |
| `created_at` | integer | 任务创建时间戳（Unix 时间戳）                                      |

## 查询任务状态

提交后，使用以下接口轮询任务进度：

```text theme={null}
GET https://geekapis.com/v1/videos/generations/{task_id}
```