> ## 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 4.0 参考生视频

> Kling 4.0 参考生视频 API 用最多 10 张参考图、5 个参考视频和 7 个主体引导生成 3–30 秒视频，在提示词中以 @Image1、@Element1 等引用。

> [!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)接口获取结果。

Kling 4.0 参考生视频根据参考图、参考视频和可复用的主体（element）生成 3–30 秒视频，让角色、产品和场景保持一致。在提示词中按位置引用每个参考，例如 `@Image1`、`@Video1` 或 `@Element1`。

Kling 4.0 是快手 Kling AI 的视频模型。Vidgo 提供四个 model ID：[文生视频](https://docs.vidgo.ai/zh/api-manual/video-series/kwaivgi-kling-v4-0-text-to-video.md)、[图生视频](https://docs.vidgo.ai/zh/api-manual/video-series/kwaivgi-kling-v4-0-image-to-video.md)、[参考生视频](https://docs.vidgo.ai/zh/api-manual/video-series/kwaivgi-kling-v4-0-reference-to-video.md)和[视频编辑](https://docs.vidgo.ai/zh/api-manual/video-series/kwaivgi-kling-v4-0-video-edit.md)。

## 模型

* **kwaivgi/kling-v4.0/reference-to-video** — Kling 4.0 参考生视频，使用图片、视频和主体，3–30 秒，720p 或 1080p。

## 功能

* 最多 10 张参考图、5 个参考视频和 7 个主体，合计最多 15 个素材。
* 主体可由同一对象的 2–4 张图片或一个视频构成。
* 可通过 `image_urls` 指定起始帧。
* 支持单段或多镜头提示词；3–30 秒，720p 或 1080p。
* 五种宽高比：`auto`、`16:9`、`9:16`、`1:1`、`21:9`。

## 输入模式

至少传一种参考输入，也可以组合使用：

* **参考图**（`reference_image_urls`）：用 `@Image1`、`@Image2`……引用。
* **参考视频**（`reference_video_urls`）：用 `@Video1`、`@Video2`……引用，按输入视频计费。
* **主体**（`kling_elements`）：用 `@Element1`、`@Element2`……引用。视频主体按输入视频计费。

传一张图片的 `image_urls` 可固定开场画面。然后选择单段 `prompt` 或 `multi_prompt` 镜头列表：

* **单段提示词**：传 `prompt`，可选传 `duration`。
* **多镜头**：传 `multi_prompt`，每个镜头一项。视频时长为各镜头时长之和；`duration` 可省略，或设为该总和。

## 必填参数

* `reference_image_urls`、`reference_video_urls`、`kling_elements` 至少传一个。
* `prompt`（string）**或** `multi_prompt`（object\[]）：必须且只能传一个。
  * `prompt`：去除首尾空白后 1–26,000 个字符。
  * `multi_prompt`：非空的镜头列表 `{prompt, duration?}`。每个镜头的 `prompt` 为 1–512 个字符，`duration` 为 `1`–`30` 的整数（默认 `5`）。各镜头时长之和须为 3–30 秒。

## 可选参数

* `reference_image_urls`（string\[]）：最多 10 个公开 HTTP(S) 图片 URL。
* `reference_video_urls`（string\[]）：最多 5 个公开 HTTP(S) 视频 URL，每个 3–30 秒。
* `kling_elements`（object\[]）：最多 7 个主体，其中视频主体最多 3 个。每个主体必须且只能包含以下之一：
  * `element_input_urls`（string\[]）：该主体的 2–4 个图片 URL。
  * `element_input_video_urls`（string\[]）：该主体的 1 个视频 URL（3–30 秒）。
* `image_urls`（string\[]）：一个起始帧图片 URL。
* `duration`（integer）：输出时长，`3`–`30` 秒。默认 `5`；使用 `multi_prompt` 时默认为各镜头时长之和，显式传入的值必须与之相等。
* `resolution`（string）：`720p` 或 `1080p`。默认 `720p`。
* `aspect_ratio`（string）：`auto`、`16:9`、`9:16`、`1:1` 或 `21:9`。默认 `auto`。

## 输出

任务完成后，[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)和回调内容的 `files` 数组中会返回一个带音轨的 MP4 视频。

## 示例

* **参考图**：一张角色图和一张咖啡馆图，分别以 `@Image1`、`@Image2` 引用，720p，8 秒。
* **主体加参考视频，带回调**：由两张图片构成的机器人主体，加一段以 `@Video1` 引用的舞蹈视频，1080p，10 秒，`9:16`。

## 注意事项

* 数量限制：起始帧加参考图 ≤ 10；所有素材（起始帧、参考图、参考视频、主体）≤ 15；视频主体 ≤ 3。
* 输入视频会在服务端下载并检测时长（每个最大 100 MB）。每个视频须为 3–30 秒，所有输入视频合计不得超过 30 秒。
* 主体中的 `voice_id` 及其他多余字段会返回 400。
* 上文未列出的字段会返回 400。`model` 和 `callback_url` 放在请求根级，不要放进 `input`。
* 积分在提交时预扣，取决于 `resolution` 和时长。有输入视频时使用单独的输入视频费率，计费秒数 = 输出时长 + max（输出时长，输入视频总时长）；输入视频时长先求和再向上取整到整秒。任务失败会全额退还。当前费率见[定价页](https://vidgo.ai/apis/api-pricing)。只含参考图或图片主体的请求按标准费率、以输出时长计费。
* 仅支持 720p 或 1080p 输出；本模型没有 4K 或 HDR 档位，没有音频开关，也不支持 `seed`。


## OpenAPI

````yaml zh/api-manual/video-series/kwaivgi-kling-v4-0-reference-to-video.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - Kling 4.0 参考生视频
  description: >-
    Kling 4.0 参考生视频 API 用最多 10 张参考图、5 个参考视频和 7 个主体引导生成 3–30 秒视频，在提示词中以
    @Image1、@Element1 等引用。
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Video Series
      summary: Kling 4.0 参考生视频
      description: >-
        `reference_image_urls`、`reference_video_urls`、`kling_elements`
        至少传一个，`prompt` 与 `multi_prompt` 必须且只能传一个。起始帧加参考图最多 10 张，所有素材合计最多 15
        个。输入视频会在服务端下载并检测时长（每个最大 100 MB）。每个视频须为 3–30 秒，所有输入视频合计不得超过 30 秒。
      operationId: submit_kwaivgi_kling_v4_0_reference_to_video
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  description: 模型 ID，填 `kwaivgi/kling-v4.0/reference-to-video`。
                  example: kwaivgi/kling-v4.0/reference-to-video
                callback_url:
                  type: string
                  format: uri
                  nullable: true
                  description: >-
                    可选的公开 HTTP(S) 地址，任务变为 `finished` 或 `failed` 时会收到 POST
                    请求。建议使用 HTTPS。省略、传 `null` 或空字符串即不发送回调。
                  example: https://your-domain.com/callback
                input:
                  type: object
                  properties:
                    reference_image_urls:
                      type: array
                      items:
                        type: string
                        format: uri
                      maxItems: 10
                      description: >-
                        最多 10 个公开 HTTP(S) 参考图 URL（与起始帧合计不超过 10 张）。在提示词中按数组顺序用
                        `@Image1`、`@Image2`……引用。
                    reference_video_urls:
                      type: array
                      items:
                        type: string
                        format: uri
                      maxItems: 5
                      description: >-
                        最多 5 个公开 HTTP(S) 参考视频 URL，每个 3–30 秒，合计不超过 30 秒。用
                        `@Video1`、`@Video2`……引用，按输入视频计费。
                    kling_elements:
                      type: array
                      items:
                        type: object
                        properties:
                          element_input_urls:
                            type: array
                            items:
                              type: string
                              format: uri
                            minItems: 2
                            maxItems: 4
                            description: 2–4 个展示同一主体的公开 HTTP(S) 图片 URL。
                          element_input_video_urls:
                            type: array
                            items:
                              type: string
                              format: uri
                            minItems: 1
                            maxItems: 1
                            description: 恰好一个该主体的公开 HTTP(S) 视频 URL（3–30 秒），按输入视频计费。
                        additionalProperties: false
                        description: 一个 element：同一主体的多张图片或一个视频。
                      maxItems: 7
                      description: >-
                        最多 7 个主体（element），其中视频主体最多 3 个。每个 element 必须且只能包含
                        `element_input_urls` 或 `element_input_video_urls`
                        之一。在提示词中按数组顺序用 `@Element1`、`@Element2`……引用。
                    image_urls:
                      type: array
                      items:
                        type: string
                        format: uri
                      minItems: 1
                      maxItems: 1
                      description: 可选的起始帧：最多一个公开 HTTP(S) 图片 URL。
                    prompt:
                      type: string
                      minLength: 1
                      maxLength: 26000
                      description: >-
                        文本提示词，去除首尾空白后 1–26,000 个字符。`prompt` 与 `multi_prompt`
                        必须且只能传一个。
                    multi_prompt:
                      type: array
                      items:
                        type: object
                        required:
                          - prompt
                        properties:
                          prompt:
                            type: string
                            minLength: 1
                            maxLength: 512
                            description: 镜头提示词，1–512 个字符。
                          duration:
                            type: integer
                            minimum: 1
                            maximum: 30
                            default: 5
                            description: 镜头时长，单位秒（整数）。
                        additionalProperties: false
                        description: 一个镜头。
                      minItems: 1
                      description: >-
                        多镜头提示词：非空的镜头列表，每个镜头有自己的 `prompt` 和可选的
                        `duration`。各镜头时长之和须为 3–30 秒。`prompt` 与 `multi_prompt`
                        必须且只能传一个。
                    duration:
                      type: integer
                      minimum: 3
                      maximum: 30
                      default: 5
                      description: 输出时长，单位秒（整数）。使用 `multi_prompt` 时默认为各镜头时长之和，若传入则必须与之相等。
                    resolution:
                      type: string
                      enum:
                        - 720p
                        - 1080p
                      default: 720p
                      description: 输出分辨率，决定计费档位。
                    aspect_ratio:
                      type: string
                      enum:
                        - auto
                        - '16:9'
                        - '9:16'
                        - '1:1'
                        - '21:9'
                      default: auto
                      description: 输出宽高比。`auto` 由模型决定。
                  additionalProperties: false
                  description: 生成参数。
            examples:
              reference_images:
                summary: 参考图
                value:
                  model: kwaivgi/kling-v4.0/reference-to-video
                  input:
                    reference_image_urls:
                      - https://example.com/character.png
                      - https://example.com/cafe.png
                    prompt: >-
                      @Image1 sits at a window table in the cafe from @Image2,
                      sips coffee and waves at the camera, warm afternoon light
                    duration: 8
                    resolution: 720p
                    aspect_ratio: '16:9'
              elements_and_video:
                summary: 主体加参考视频，带回调
                value:
                  model: kwaivgi/kling-v4.0/reference-to-video
                  callback_url: https://your-domain.com/callback
                  input:
                    kling_elements:
                      - element_input_urls:
                          - https://example.com/robot-front.png
                          - https://example.com/robot-side.png
                    reference_video_urls:
                      - https://example.com/dance-move.mp4
                    prompt: >-
                      @Element1 performs the dance from @Video1 on a rooftop at
                      sunset, wide shot
                    duration: 10
                    resolution: 1080p
                    aspect_ratio: '9:16'
      responses:
        '200':
          description: 任务已提交
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - data
                properties:
                  code:
                    type: integer
                    enum:
                      - 200
                    description: HTTP 状态码。
                  data:
                    type: object
                    required:
                      - task_id
                      - status
                      - created_time
                    properties:
                      task_id:
                        type: string
                        description: >-
                          任务
                          ID，用于[查询任务状态](/zh/api-manual/task-management/status)。
                      status:
                        type: string
                        enum:
                          - not_started
                        description: 任务的初始状态。
                      created_time:
                        type: string
                        format: date-time
                        description: 任务创建时间（ISO 8601）。
              example:
                code: 200
                data:
                  task_id: task-unified-1762160000-abc123
                  status: not_started
                  created_time: '2026-11-03T10:30:00'
        '400':
          description: 输入无效、字段不受支持、媒体无法访问或积分不足
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '401':
          description: 凭证无效
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '403':
          description: 拒绝访问
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '404':
          description: 模型未知或已停用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '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: {}
                    description: 错误信息。
        '429':
          description: 超出速率限制或 API Key 积分限额
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '500':
          description: 内部错误
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '502':
          description: 无法创建上游生成任务
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '503':
          description: 所请求的模型暂时不可用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证


        获取 API Key：


        进入 **仪表盘 → API 密钥**（[API Key
        管理页面](https://vidgo.ai/apis/dashboard/api-key)）获取你的 API Key


        在请求头中添加：


        ```

        Authorization: Bearer VIDGO_API_KEY

        ```

````

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