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

# Kling 视频生成

> 使用 `POST /v1/videos` 调用 Kling 模型提交异步视频任务。

# Kling 视频生成

Kling 使用 `POST /v1/videos` 提交任务，并以 JSON 提交为主。

* 路由入口是 `POST /v1/videos`。
* 当前使用 JSON 提交。
* 支持文生视频、图生视频、首尾帧生视频等多种场景。
* 通过 `metadata` 字段传递扩展参数，包括输出配置、场景类型等。
* 提交成功后返回任务 `id` 与 `status`，后续用 [任务状态查询](./query) 轮询结果。

## 支持模型

* `Kling-3.0-Omni`：Kling 3.0 全能版
* `Kling-2.6`：Kling 2.6 版本
* `Kling-2.5`：Kling 2.5 版本

## 方法与路径

```http theme={null}
POST /v1/videos
```

## 请求示例

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "Kling-3.0-Omni",
      "prompt": "赛博朋克城市夜景，镜头慢慢推进",
      "seconds": "5",
      "metadata": {
        "output_config": {
          "resolution": "720P",
          "aspect_ratio": "16:9"
        }
      }
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/v1/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "Kling-3.0-Omni",
          "prompt": "赛博朋克城市夜景，镜头慢慢推进",
          "seconds": "5",
          "metadata": {
              "output_config": {
                  "resolution": "720P",
                  "aspect_ratio": "16:9",
              }
          },
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://octopusx.ai/v1/videos", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "Kling-3.0-Omni",
      prompt: "赛博朋克城市夜景，镜头慢慢推进",
      seconds: "5",
      metadata: {
        output_config: {
          resolution: "720P",
          aspect_ratio: "16:9",
        },
      },
    }),
  });

  console.log(await response.json());
  ```
</CodeGroup>

## 场景示例

### 文生视频

```json theme={null}
{
  "model": "Kling-3.0-Omni",
  "prompt": "赛博朋克城市夜景，镜头慢慢推进",
  "seconds": "5",
  "metadata": {
    "output_config": {
      "resolution": "720P",
      "aspect_ratio": "16:9"
    }
  }
}
```

### 图生视频

```json theme={null}
{
  "model": "Kling-3.0-Omni",
  "prompt": "让人物向前走并微笑",
  "image": "https://example.com/character.png",
  "seconds": "5",
  "metadata": {
    "output_config": {
      "resolution": "1080P",
      "aspect_ratio": "9:16"
    }
  }
}
```

### 首尾帧生视频

```json theme={null}
{
  "model": "Kling-3.0-Omni",
  "prompt": "死寂系统空间中，角色被蓝色面板照亮",
  "seconds": "15",
  "size": "720x1280",
  "metadata": {
    "output_config": {
      "duration": 15,
      "resolution": "720P",
      "aspect_ratio": "9:16",
      "audio_generation": "Enabled"
    },
    "last_frame_url": "https://example.com/last-frame.png"
  }
}
```

### 动作控制

```json theme={null}
{
  "model": "Kling-3.0-Omni",
  "prompt": "人物挥手打招呼",
  "image": "https://example.com/character.png",
  "seconds": "5",
  "metadata": {
    "scene_type": "motion_control",
    "motion_level": "pro",
    "output_config": {
      "resolution": "1080P",
      "aspect_ratio": "16:9"
    }
  }
}
```

## 响应示例

> **注意**：响应中的 `model` 字段可能包含计费规格后缀（如 `720p-ref-audio`），与请求传入的模型名称不同。

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "video_123",
    "task_id": "video_123",
    "object": "video",
    "model": "kling-3.0-omni-720p-ref-audio",
    "status": "queued",
    "progress": 0,
    "created_at": 1712697600
  }
  ```
</ResponseExample>

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  模型名称。例如 `Kling-3.0-Omni`、`Kling-2.6`、`Kling-2.5`。
</ParamField>

<ParamField body="prompt" type="string" required>
  提示词。生成视频的文本描述,支持中文和英文。
</ParamField>

<ParamField body="seconds" type="string">
  视频时长。例如 `5`、`10`、`15`。
</ParamField>

<ParamField body="size" type="string">
  视频尺寸。快速尺寸输入,例如 `720x1280`。
</ParamField>

<ParamField body="image" type="string">
  参考图片。参考图片 URL。
</ParamField>

<ParamField body="metadata" type="object">
  元数据。扩展参数容器,建议把上游原生参数都放到 metadata 中。
</ParamField>

<ParamField body="metadata.output_config" type="object">
  输出配置。建议把原生参数都放到 output\_config 中。

  * `duration`:时长(秒)
  * `resolution`:分辨率(`720P`、`1080P`)
  * `aspect_ratio`:画幅比例(`16:9`、`9:16`、`1:1`)
  * `audio_generation`:音频生成(`Enabled`、`Disabled`)
</ParamField>

<ParamField body="metadata.scene_type" type="string">
  场景类型。示例:`motion_control`(动作控制)、`avatar_i2v`(数字人生成)、`lip_sync`(对口型)、`template_effect`(模板特效)。
</ParamField>

<ParamField body="metadata.motion_level" type="string">
  运动等级。示例:`std`(标准)、`pro`(专业,用于动作控制计费分档)。
</ParamField>

<ParamField body="metadata.offpeak" type="boolean">
  是否错峰计费。`true`:错峰生成视频;`false`:即时生成视频。
</ParamField>

<ParamField body="metadata.last_frame_url" type="string">
  首尾帧中的尾帧。首尾帧生视频时指定尾帧图片 URL。
</ParamField>

<ParamField body="metadata.video_url" type="string">
  参考视频 URL。
</ParamField>

<ParamField body="metadata.file_infos" type="string">
  文件信息。原生 FileInfos 透传(高级用法)。
</ParamField>

<ParamField body="metadata.ext_info" type="string">
  扩展信息。原生 ExtInfo 字符串透传(高级用法)。
</ParamField>

## Response

<ResponseField name="id" type="string">
  任务 ID。
</ResponseField>

<ResponseField name="task_id" type="string">
  任务 ID（与 id 相同）。
</ResponseField>

<ResponseField name="object" type="string">
  固定为 `video`。
</ResponseField>

<ResponseField name="model" type="string">
  模型名称。
</ResponseField>

<ResponseField name="status" type="string">
  任务状态，常见值包括 `queued`、`processing`、`completed`、`failed`、`cancelled`。
</ResponseField>

<ResponseField name="progress" type="integer">
  进度百分比（0-100）。
</ResponseField>

<ResponseField name="created_at" type="integer">
  创建时间（Unix 时间戳）。
</ResponseField>

## 相关接口

* [Kling 视频概览](./overview)
* [任务状态查询](./query)