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

# Kling v3 Omni

> 可灵 3.0-Omni 视频生成模型，在 Kling v3 基础上额外支持参考视频（视频源编辑 / 视频特征参考）



## OpenAPI

````yaml /zh/openapi/videos/kling-v3-omni.yaml POST /v1/videos/generate
openapi: 3.1.0
info:
  title: Kling v3 Omni
  version: '1.0'
  description: 可灵 3.0-Omni 视频生成模型，在 Kling v3 基础上额外支持参考视频（视频源编辑 / 视频特征参考）。
servers:
  - url: https://openapi.imini.ai/imini/router
security:
  - ApiKeyAuth: []
paths:
  /v1/videos/generate:
    post:
      summary: Kling v3 Omni
      description: |
        提交异步的视频生成任务，后续需通过查询接口轮询结果。

        > 模型 ID：`kling/kling-v3-omni` · 底层：可灵 3.0-Omni

        相比 `kling/kling-v3`：
        - 额外支持 `reference_videos`（视频源编辑 / 视频特征参考），最多 **1** 段；
        - `extra_params` 不支持 `camera_control`。
      operationId: generateKlingV3Omni
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
              properties:
                model:
                  type: string
                  description: 固定值 `kling/kling-v3-omni`
                prompt:
                  type: string
                  description: >
                    提示词，可包含正向与负向描述，长度不超过 **2500** 字符。


                    Omni 模型支持在提示词中通过 `<<<>>>`
                    语法引用主体、图片、视频等素材，例如：`<<<element_1>>>`、`<<<image_1>>>`、`<<<video_1>>>`。


                    > **必填规则**：

                    > - 当 `extra_params.multi_shot=false`，或
                    `extra_params.multi_shot=true` 且
                    `extra_params.shot_type=intelligence` 时，本字段不得为空；

                    > - 当 `extra_params.multi_shot=true` 且
                    `extra_params.shot_type=customize` 时，本字段被忽略，各分镜提示词由
                    `extra_params.multi_prompt` 提供。
                  example: >-
                    A slow pan across a misty mountain valley at sunrise,
                    cinematic
                resolution:
                  type: string
                  description: 输出分辨率，默认 `720P`。
                  default: 720P
                  enum:
                    - 720P
                    - 1080P
                aspect_ratio:
                  type: string
                  description: 输出宽高比，默认 `16:9`。
                  default: '16:9'
                  enum:
                    - '16:9'
                    - '9:16'
                    - '1:1'
                duration:
                  type: integer
                  description: >
                    视频时长（秒），默认 `5`。枚举值：`3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
                    15`。


                    >
                    使用视频编辑功能（`reference_videos[].refer_type=base`）时，本参数无效——输出时长与输入视频一致，按输入视频时长四舍五入取整计费。
                  default: 5
                  enum:
                    - 3
                    - 4
                    - 5
                    - 6
                    - 7
                    - 8
                    - 9
                    - 10
                    - 11
                    - 12
                    - 13
                    - 14
                    - 15
                generate_audio:
                  type: boolean
                  description: 是否生成声音，默认 `false`。
                  default: false
                reference_images:
                  type: array
                  description: >
                    参考图列表。可作为主体 / 场景 / 风格参考，也可作为视频首帧或尾帧。


                    **输入模式**（由 `reference_type` 组合决定）：

                    - **图生视频**：1 张 `first_frame`；

                    - **首尾帧生视频**：1 张 `first_frame` + 1 张
                    `last_frame`（暂不支持仅尾帧——传入 `last_frame` 时必须同时提供
                    `first_frame`）；

                    - **多参考图生视频**：N 张 `asset`（非首尾帧的素材可省略 `reference_type`，默认即为
                    `asset`）。


                    **与 `reference_videos` 的组合规则**：

                    - 传入
                    `reference_videos[].refer_type=base`（待编辑视频）时，`reference_images`
                    不可使用 `first_frame` / `last_frame`，仅支持 `asset`；

                    - 其他情况下 `asset` 类型可与 `reference_videos` 共存。


                    **图片要求**：

                    - 格式：`jpg` / `jpeg` / `png`；

                    - 大小 ≤ **10 MB**；

                    - 宽高尺寸 ≥ **300px**，宽高比介于 `1:2.5 ~ 2.5:1` 之间。


                    **数量上限**（"参考图 + 多图主体" 总数）：

                    - 无参考视频，仅含多图主体：**≤ 7**；

                    - 无参考视频，含视频主体：**≤ 4**；

                    - 有参考视频，仅含多图主体：**≤ 4**。


                    > 多图主体 / 视频主体通过 `prompt` 中的 `<<<image_n>>>` /
                    `<<<video_n>>>` 等占位符引用。
                  maxItems: 7
                  items:
                    type: object
                    required:
                      - url
                    properties:
                      url:
                        type: string
                        description: |
                          图片地址，支持两种形式：
                          **1)** 公网可访问 URL（`http://` 或 `https://`）；
                          **2)** Data URI base64（`data:image/` 开头）。
                      reference_type:
                        type: string
                        description: |
                          参考类型：
                          - `asset` — 通用素材参考（默认）
                          - `first_frame` — 首帧
                          - `last_frame` — 尾帧
                        default: asset
                        enum:
                          - asset
                          - first_frame
                          - last_frame
                reference_videos:
                  type: array
                  description: >
                    参考视频列表。至多 **1** 段。


                    **两种用途**（由 `refer_type` 区分）：

                    - `base`（默认）— **待编辑视频**，对原视频直接重绘/编辑；此模式下不能再通过
                    `reference_images` 指定 `first_frame` / `last_frame`；

                    - `feature` — **特征参考视频**，仅提取运动/风格等特征辅助生成。


                    通过 `keep_original_sound` 选择是否保留原视频音轨——该参数对 `feature` 同样生效。


                    > 传入参考视频时，`generate_audio` 将被强制视为 `false`（不会额外生成音频）。


                    **视频要求**：

                    - 格式：`MP4` / `MOV`；

                    - 大小 ≤ **200 MB**；

                    - 时长 ≥ **3s**（上限随模型版本而定）；

                    - 宽高尺寸：**720px ~ 2160px**（含）；

                    - 帧率：`24 ~ 60 fps`（输出统一为 24 fps）；

                    - 仅支持公网可访问 URL，不支持 base64。
                  maxItems: 1
                  items:
                    type: object
                    required:
                      - url
                    properties:
                      url:
                        type: string
                        description: 公网可访问的视频 URL，不支持 base64。
                      refer_type:
                        type: string
                        description: |
                          参考类型：
                          - `base` — 待编辑视频（默认）
                          - `feature` — 特征参考视频（仅提取运动/风格特征）
                        default: base
                        enum:
                          - base
                          - feature
                      keep_original_sound:
                        type: boolean
                        description: 是否保留原视频音轨。留空表示跟随模型默认。
                extra_params:
                  type: object
                  description: |
                    可灵官方扩展参数，全部选填。
                  properties:
                    multi_shot:
                      type: boolean
                      default: false
                      description: |
                        是否启用多镜头（分镜）模式。
                        - `true`：开启分镜，此时 `prompt` 无效，且不支持首尾帧生视频；
                        - `false`：关闭分镜，此时 `shot_type` 与 `multi_prompt` 无效。
                    shot_type:
                      type: string
                      description: |
                        分镜类型，仅在 `multi_shot=true` 时生效。
                        - `intelligence` — 智能分镜，模型按 `prompt` 自动拆分镜头；
                        - `customize` — 自定义分镜，由 `multi_prompt` 明确每个分镜。
                      enum:
                        - intelligence
                        - customize
                    multi_prompt:
                      type: array
                      description: >
                        分镜信息列表。**当 `multi_shot=true` 且 `shot_type=customize`
                        时必填。**


                        - 至少 **1** 个、至多 **6** 个分镜；

                        - 每个分镜提示词最大长度 **512** 字符；

                        - 每个分镜时长 ≥ 1s 且不大于任务总时长；

                        - 所有分镜时长之和必须等于任务总时长 `duration`。
                      minItems: 1
                      maxItems: 6
                      items:
                        type: object
                        required:
                          - index
                          - prompt
                          - duration
                        properties:
                          index:
                            type: integer
                            description: 分镜序号，从 `1` 开始。
                          prompt:
                            type: string
                            description: 当前分镜的提示词，最大 512 字符。
                            maxLength: 512
                          duration:
                            type: string
                            description: 当前分镜时长（秒），字符串形式传入，如 `"5"`。取值 ≥ 1 且 ≤ 任务总时长。
                            example: '5'
                  additionalProperties: true
            examples:
              Text to Video:
                summary: Text to Video
                value:
                  model: kling/kling-v3-omni
                  prompt: >-
                    A slow pan across a misty mountain valley at sunrise,
                    cinematic
                  resolution: 720P
                  aspect_ratio: '16:9'
                  duration: 5
              Image to Video:
                summary: Image to Video
                value:
                  model: kling/kling-v3-omni
                  prompt: The mountain comes alive as birds fly past
                  reference_images:
                    - url: https://example.com/first.jpg
                      reference_type: first_frame
                  resolution: 1080P
                  aspect_ratio: '16:9'
                  duration: 5
              Video Edit (base):
                summary: Video Edit (base)
                value:
                  model: kling/kling-v3-omni
                  prompt: Re-imagine the scene in neon cyberpunk style
                  reference_videos:
                    - url: https://example.com/source.mp4
                      refer_type: base
                      keep_original_sound: false
                  resolution: 1080P
                  aspect_ratio: '16:9'
                  duration: 5
              Video Feature Reference:
                summary: Video Feature Reference
                value:
                  model: kling/kling-v3-omni
                  prompt: A tiger walking across a snowy plain
                  reference_videos:
                    - url: https://example.com/reference-motion.mp4
                      refer_type: feature
                  resolution: 720P
                  aspect_ratio: '16:9'
                  duration: 5
      responses:
        '200':
          description: 提交成功（异步模式）
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                    description: 任务唯一 ID，用于后续轮询查询
                    example: task_2042864638838083584
                  model:
                    type: string
                    description: 本次任务使用的模型 ID
                    example: kling/kling-v3-omni
                  created_at:
                    type: string
                    description: 任务创建时间（ISO 8601）
                    example: '2026-04-13T07:17:39.146Z'
                  request_id:
                    type: string
                    description: 请求唯一 ID
                    example: 291a4117-9df8-4349-aee1-bdf8ffcacb9a
        '400':
          description: Validation Error (e.g. invalid parameter, invalid prompt)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Error code
                        example: INVALID_PARAMETER
                      message:
                        type: string
                        description: Error message details
                        example: reference_videos only supports at most 1 entry
                      status:
                        type: integer
                        description: HTTP status code
                        example: 400
                      request_id:
                        type: string
                        description: Unique request identifier
                        example: req_abc123
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >
        在请求 Header 中传入 `Authorization: Bearer <YOUR_API_KEY>`。前往 [API Keys
        管理页](https://imini.ai/zh/api-keys) 创建和管理 API Key。

````