> ## 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 动作控制

> 可灵 3.0 动作控制——以参考图片中的人物为主体，复刻参考视频的动作生成新视频



## OpenAPI

````yaml /zh/openapi/videos/kling-v3-motion-control.yaml POST /v1/videos/generate
openapi: 3.1.0
info:
  title: Kling v3 Motion Control
  version: '1.0'
  description: 可灵 3.0 动作控制模型。以参考图片中的人物为主体，复刻参考视频中的动作生成新视频。
servers:
  - url: https://openapi.imini.ai/imini/router
security:
  - ApiKeyAuth: []
paths:
  /v1/videos/generate:
    post:
      summary: Kling v3 Motion Control
      description: >
        提交异步的视频生成任务，后续需通过查询接口轮询结果。


        > 模型 ID：`kling/kling-v3-motion-control` · 底层：可灵 3.0 动作控制


        以 `reference_images` 提供主体（人物 / 背景 / 风格），以 `reference_videos`
        提供动作源，生成视频中的人物将复刻参考视频的动作。
      operationId: generateKlingV3MotionControl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
              properties:
                model:
                  type: string
                  description: 固定值 `kling/kling-v3-motion-control`
                prompt:
                  type: string
                  description: |
                    文本提示词，可包含正向与负向描述，长度不超过 **2500** 字符。
                  example: A dancer performs graceful movements in a sunlit studio
                resolution:
                  type: string
                  description: 输出分辨率，默认 `720P`。
                  default: 720P
                  enum:
                    - 720P
                    - 1080P
                reference_images:
                  type: array
                  description: |
                    参考图像，**仅支持 1 张**。生成视频中的人物、背景等元素均以该图为准。

                    **内容要求**：
                    - 人物比例尽量与参考视频动作比例一致，避免用全身动作驱动半身人物；
                    - 人物需清晰露出完整的上半身或全身肢体及头部，避免遮挡；
                    - 避免极端朝向（如倒立、平卧），人物占画面比例不宜过低；
                    - 支持真实 / 风格化角色（含人物 / 类人动物 / 部分纯动物 / 部分类人肢体比例角色）。

                    **图片要求**：
                    - 格式：`jpg` / `jpeg` / `png`；
                    - 大小 ≤ **10 MB**；
                    - 宽高尺寸：**300px ~ 65536px**；
                    - 宽高比介于 `1:2.5 ~ 2.5:1` 之间。
                  maxItems: 1
                  items:
                    type: object
                    required:
                      - url
                    properties:
                      url:
                        type: string
                        description: |
                          图片地址，支持两种形式：
                          **1)** 公网可访问 URL（`http://` 或 `https://`）；
                          **2)** Data URI base64（`data:image/` 开头）。
                reference_videos:
                  type: array
                  description: >
                    参考视频，**仅支持 1 段**。生成视频中的人物动作与该视频保持一致。


                    **内容要求**：

                    - 人物需清晰露出完整的上半身或全身肢体及头部，避免遮挡；

                    - 建议上传单人动作视频；多人画面会选取占比最大的人物进行生成；

                    - 推荐真人动作，部分风格化 / 类人肢体比例角色可通过；

                    - 一镜到底、角色始终在画面内，避免切镜、运镜（否则会被截取）；

                    - 动作避免过快，相对平稳的动作生成效果更佳。


                    **视频要求**：

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

                    - 大小 ≤ **100 MB**；

                    - 宽高尺寸（长宽边长均需满足）：**340px ~ 3850px**；

                    - 时长下限 **3s**，上限取决于 `extra_params.character_orientation`：
                      - `video`：**≤ 30s**；
                      - `image`：**≤ 10s**。
                    - 仅支持公网 URL，不支持 base64。


                    > 如果动作难度高、速度快，模型可能只提取其中的有效动作时长（最短需 **3s**
                    连续可用动作即可），生成结果时长可能短于上传时长。
                  maxItems: 1
                  items:
                    type: object
                    required:
                      - url
                    properties:
                      url:
                        type: string
                        description: 公网可访问的视频 URL，不支持 base64。
                generate_audio:
                  type: boolean
                  description: 是否生成声音，默认 `false`。
                  default: false
                extra_params:
                  type: object
                  description: 扩展参数。
                  required:
                    - character_orientation
                  properties:
                    character_orientation:
                      type: string
                      description: |
                        **必填。** 生成视频中人物的朝向参考来源。
                        - `image` — 与参考图片中人物朝向一致；此时参考视频时长须 ≤ **10s**；
                        - `video` — 与参考视频中人物朝向一致；此时参考视频时长须 ≤ **30s**。

                        > 使用主体引用（`<<<element_x>>>`）时，暂时只能取 `video`（参考视频中人物朝向）。
                      enum:
                        - image
                        - video
                  additionalProperties: true
            examples:
              Motion Control (follow video orientation):
                summary: Motion Control (follow video orientation)
                value:
                  model: kling/kling-v3-motion-control
                  prompt: A dancer performs graceful movements in a sunlit studio
                  reference_images:
                    - url: https://example.com/character.jpg
                  reference_videos:
                    - url: https://example.com/motion-source.mp4
                  resolution: 720P
                  generate_audio: false
                  extra_params:
                    character_orientation: video
              Motion Control (follow image orientation):
                summary: Motion Control (follow image orientation)
                value:
                  model: kling/kling-v3-motion-control
                  prompt: >-
                    A stylized character mimics the reference motion in a
                    cinematic scene
                  reference_images:
                    - url: https://example.com/character.jpg
                  reference_videos:
                    - url: https://example.com/motion-source-10s.mp4
                  resolution: 1080P
                  extra_params:
                    character_orientation: image
      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-motion-control
                  created_at:
                    type: string
                    description: 任务创建时间（ISO 8601）
                    example: '2026-04-21T07: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 duration must not exceed 10 seconds
                          when character_orientation is "image"
                      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。

````