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

# Kling O3 Pro 文生视频

> 使用 Kling O3 Pro 根据文本提示词生成 3–15 秒的视频。支持单镜头和多镜头生成。需显式设置 sound；多镜头需要开启音频。

> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)接口获取结果。

## 参数

使用模型 `kwaivgi/kling-video-o3-pro/text-to-video`。生成参数放在 `input` 中。

* **`prompt`**：multi\_shots=false 时必填。描述场景、动作和运镜。使用非空文本，去除首尾空白后最多 2,500 个字符。multi\_shots=true 时省略 prompt。
* **`multi_prompt`**：multi\_shots=true 时必填；单镜头模式下省略。至少提供一个镜头，每个镜头包含不超过 2,500 个字符的非空 prompt 和 1–12 秒的整数 duration。各镜头时长之和必须等于顶层 duration（3–15 秒）。镜头对象中的多余字段会被忽略。
* **`duration`**：必填整数，3 到 15 秒。多镜头模式下必须等于所有镜头时长之和。积分按该值计算。
* **`multi_shots`**：必填：单镜头显式传 false，多镜头传 true。单镜头模式需要 prompt。多镜头模式需要 multi\_prompt 和 sound=true，且顶层不能有非空 prompt。省略该字段会报错。
* **`sound`**：必填：显式传 true 生成音频，或传 false 生成无音频视频。单镜头模式两者均可；多镜头模式必须为 true。
* **`aspect_ratio`**：可选：16:9（横屏）、9:16（竖屏）或 1:1（方形）。设置视频宽高比。

请使用标准 JSON 数字和布尔值。为兼容起见，也接受 "5" 这样的整数字符串。布尔字符串 true/1/yes/y/on 表示 true；false/0/no/n/off 表示 false。这些字符串不区分大小写，并会去除首尾空白。布尔字段也接受数字 1 和 0。数字和布尔类型的提示词会转换为文本；0、false 和 null 视为空。提示词不接受对象和数组。不支持的 input 字段会被拒绝。

## 计费因素

计费取决于模型档位、视频时长（`duration`）以及是否生成音频（`sound`），按生成的秒数计费。

生成失败的任务会退款。

## 默认示例：轻声道歉

这与[模型页面](https://vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/text-to-video)上展示的默认示例相同。

```json theme={null}
{
  "model": "kwaivgi/kling-video-o3-pro/text-to-video",
  "input": {
    "duration": 5,
    "sound": true,
    "multi_shots": true,
    "multi_prompt": [
      {
        "prompt": "Cinematic whimsical realism in a warm oak library. Medium two-shot: a small ivory robot with an oval face and amber eyes shelves a blue book, accidentally knocking one red book onto the floor. Beside it, an adult librarian wears a green cardigan and round glasses. Both remain visible under warm reading lamps. One distinct book thud against quiet room tone. Unmarked book covers. No text, logos or watermarks.",
        "duration": 2
      },
      {
        "prompt": "Cut closer to the same ivory robot and green-cardigan librarian in the same oak library. The librarian raises one finger to her lips. The robot tilts its head apologetically and softly says exactly \"Sorry.\" in a gentle robotic voice, synchronized with its small mouth light. Preserve their appearance, positions and warm lighting. End in an embarrassed pause; no music. No text, logos or watermarks.",
        "duration": 3
      }
    ],
    "aspect_ratio": "16:9"
  }
}
```

<video controls playsInline preload="metadata" poster="https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/text-to-video/v1/01/poster.jpg" src="https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/text-to-video/v1/01/output.mp4" />

[下载该视频](https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/text-to-video/v1/01/output.mp4)

### 状态接口返回的完成结果

`GET /api/generate/status/{task_id}`

下面的响应记录的是这个已验证的示例。新的生成任务请查询你自己提交后返回的任务 ID。

```json theme={null}
{
  "code": 200,
  "data": {
    "task_id": "BRDSCRKN4Q0WH4T6",
    "status": "finished",
    "files": [
      {
        "file_type": "video",
        "file_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/text-to-video/v1/01/output.mp4"
      }
    ],
    "created_time": "2026-09-22T18:43:52",
    "error_message": null,
    "progress": 100
  }
}
```

> [!NOTE]
>
> API 对提示词的校验上限为 2,500 个字符。部分多镜头生成请求在单个镜头提示词超过 512 个字符时失败。建议每个镜头提示词控制在 512 个字符以内；该建议不改变 API 的校验上限。


## OpenAPI

````yaml zh/api-manual/video-series/kwaivgi-kling-video-o3-pro-text-to-video.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - Kling O3 Pro 文生视频
  description: 使用 Kling O3 Pro 根据文本提示词生成 3–15 秒的视频。支持单镜头和多镜头生成。需显式设置 sound；多镜头需要开启音频。
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Video Series
      summary: Kling O3 Pro 文生视频
      description: >-
        提交视频生成任务。duration、multi_shots 和 sound 必须显式提供。多镜头模式下需提供 multi_prompt、设置
        sound=true，并使各镜头时长之和等于 duration。无效参数会在上传图片、创建任务或扣费之前被拒绝。
      operationId: submit_kwaivgi_kling_video_o3_pro_text_to_video
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              additionalProperties: true
              properties:
                model:
                  type: string
                  example: kwaivgi/kling-video-o3-pro/text-to-video
                input:
                  type: object
                  required:
                    - duration
                    - multi_shots
                    - sound
                  description: >-
                    视频生成参数。请使用标准 JSON 数字和布尔值。为兼容起见，也接受 "5" 这样的整数字符串。布尔字符串
                    true/1/yes/y/on 表示 true；false/0/no/n/off 表示
                    false。这些字符串不区分大小写，并会去除首尾空白。布尔字段也接受数字 1 和
                    0。数字和布尔类型的提示词会转换为文本；0、false 和 null 视为空。提示词不接受对象和数组。
                  properties:
                    prompt:
                      type: string
                      description: >-
                        multi_shots=false 时必填。描述场景、动作和运镜。使用非空文本，去除首尾空白后最多 2,500
                        个字符。multi_shots=true 时省略 prompt。
                      maxLength: 2500
                      minLength: 1
                    multi_prompt:
                      type: array
                      items:
                        type: object
                        required:
                          - prompt
                          - duration
                        properties:
                          prompt:
                            type: string
                            description: 必填的该镜头非空文本，去除首尾空白后最多 2,500 个字符。
                            maxLength: 2500
                            minLength: 1
                          duration:
                            type: integer
                            description: 必填整数，该镜头时长 1 到 12 秒。
                            minimum: 1
                            maximum: 12
                        additionalProperties: true
                      description: >-
                        multi_shots=true 时必填；单镜头模式下省略。至少提供一个镜头，每个镜头包含不超过 2,500
                        个字符的非空 prompt 和 1–12 秒的整数 duration。各镜头时长之和必须等于顶层
                        duration（3–15 秒）。镜头对象中的多余字段会被忽略。
                      minItems: 1
                    duration:
                      type: integer
                      description: 必填整数，3 到 15 秒。多镜头模式下必须等于所有镜头时长之和。积分按该值计算。
                      minimum: 3
                      maximum: 15
                    multi_shots:
                      type: boolean
                      description: >-
                        必填：单镜头显式传 false，多镜头传 true。单镜头模式需要 prompt。多镜头模式需要
                        multi_prompt 和 sound=true，且顶层不能有非空 prompt。省略该字段会报错。
                    sound:
                      type: boolean
                      description: >-
                        必填：显式传 true 生成音频，或传 false 生成无音频视频。单镜头模式两者均可；多镜头模式必须为
                        true。
                    aspect_ratio:
                      type: string
                      description: 可选：16:9（横屏）、9:16（竖屏）或 1:1（方形）。设置视频宽高比。
                      enum:
                        - '1:1'
                        - '16:9'
                        - '9:16'
                  additionalProperties: false
                callback_url:
                  type: string
                  nullable: true
                  description: >-
                    可选的公开 HTTP(S) 接口，用于接收任务完成通知。建议使用 HTTPS。省略、传 null
                    或空字符串即可禁用回调。
              description: model 和 callback_url 放在根级。未知的根级字段会被忽略；不支持的 input 字段会被拒绝。
            examples:
              basic:
                summary: 轻声道歉
                value:
                  model: kwaivgi/kling-video-o3-pro/text-to-video
                  input:
                    duration: 5
                    sound: true
                    multi_shots: true
                    multi_prompt:
                      - prompt: >-
                          Cinematic whimsical realism in a warm oak library.
                          Medium two-shot: a small ivory robot with an oval face
                          and amber eyes shelves a blue book, accidentally
                          knocking one red book onto the floor. Beside it, an
                          adult librarian wears a green cardigan and round
                          glasses. Both remain visible under warm reading lamps.
                          One distinct book thud against quiet room tone.
                          Unmarked book covers. No text, logos or watermarks.
                        duration: 2
                      - prompt: >-
                          Cut closer to the same ivory robot and green-cardigan
                          librarian in the same oak library. The librarian
                          raises one finger to her lips. The robot tilts its
                          head apologetically and softly says exactly "Sorry."
                          in a gentle robotic voice, synchronized with its small
                          mouth light. Preserve their appearance, positions and
                          warm lighting. End in an embarrassed pause; no music.
                          No text, logos or watermarks.
                        duration: 3
                    aspect_ratio: '16:9'
              callback:
                summary: 轻声道歉（带回调）
                value:
                  model: kwaivgi/kling-video-o3-pro/text-to-video
                  input:
                    duration: 5
                    sound: true
                    multi_shots: true
                    multi_prompt:
                      - prompt: >-
                          Cinematic whimsical realism in a warm oak library.
                          Medium two-shot: a small ivory robot with an oval face
                          and amber eyes shelves a blue book, accidentally
                          knocking one red book onto the floor. Beside it, an
                          adult librarian wears a green cardigan and round
                          glasses. Both remain visible under warm reading lamps.
                          One distinct book thud against quiet room tone.
                          Unmarked book covers. No text, logos or watermarks.
                        duration: 2
                      - prompt: >-
                          Cut closer to the same ivory robot and green-cardigan
                          librarian in the same oak library. The librarian
                          raises one finger to her lips. The robot tilts its
                          head apologetically and softly says exactly "Sorry."
                          in a gentle robotic voice, synchronized with its small
                          mouth light. Preserve their appearance, positions and
                          warm lighting. End in an embarrassed pause; no music.
                          No text, logos or watermarks.
                        duration: 3
                    aspect_ratio: '16:9'
                  callback_url: https://your-domain.com/callback
      responses:
        '200':
          description: 任务已提交
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - data
                properties:
                  code:
                    type: integer
                    enum:
                      - 200
                  data:
                    type: object
                    required:
                      - task_id
                      - status
                      - created_time
                    properties:
                      task_id:
                        type: string
                      status:
                        type: string
                        enum:
                          - not_started
                          - running
                          - finished
                          - failed
                      created_time:
                        type: string
                        format: date-time
              example:
                code: 200
                data:
                  task_id: task-submitted-example
                  status: not_started
                  created_time: '2026-09-22T00:00:00Z'
        '400':
          description: 输入无效、档位不受支持、媒体无法访问或积分不足
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '401':
          description: 凭据无效
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '403':
          description: 拒绝访问
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '404':
          description: 模型未知或已停用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '408':
          description: 请求超时
          content:
            text/plain:
              schema:
                type: string
              example: Request timeout
        '422':
          description: JSON 无效或请求体不是对象
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '429':
          description: 超出请求频率或 API Key 积分限额
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '500':
          description: 内部错误
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '502':
          description: 无法创建视频生成任务
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
        '503':
          description: 该模型当前不可用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 使用 VIDGO_API_KEY。

````

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