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

# Kling Motion Control 작업 생성

> 캐릭터 이미지와 참조 동영상에서 호환 CometAPI 경로를 통해 Kling Motion Control 작업을 생성합니다.

이 엔드포인트를 사용하여 캐릭터 이미지와
참조 동영상으로 Motion Control 작업을 생성하세요.

<Warning>
  이 페이지에서는 호환 Motion Control 경로를 설명합니다. Kling Video 3.0
  Motion Control에는 별도의 API 계약이 사용됩니다.
</Warning>

## 필수 미디어

`image_url` 공개 URL 또는 원시 Base64 문자열을 허용합니다.

* 10MB 이하의 JPG, JPEG 또는 PNG 이미지를 사용하세요.
* 각 이미지의 크기는 가로와 세로 모두 300\~65,536픽셀로 설정하세요.
* 가로세로비는 1:2.5\~2.5:1로 설정하세요.
* Base64는
  `data:image/...;base64,` 접두사 없이 원시 인코딩 문자열로 전송하세요.
* 동작
  참조와 일치하는 신체 구도로 가려지지 않은 캐릭터 한 명을 표시하세요.

`video_url` 공개 MP4 또는 MOV URL을 허용합니다.

* 100MB 이하의 동영상을 사용하세요.
* 짧은 변의 길이는 최소 340픽셀로 설정하세요.
* 긴 변의 길이는 3850픽셀 이하로 설정하세요.
* 보이는 캐릭터가 한 명인 연속 촬영 영상을 사용하세요.
* 장면 전환, 카메라 변경 및 지나치게 빠른 동작은 피하세요.

<Note>
  길이 제한을 준수하고 중첩된 종료 상태 `task_status`를 확인하세요. 외부
  HTTP 200 또는 응답 `code: 0`은 쿼리 응답만 확인하며, 성공적인
  생성 결과를 의미하지는 않습니다.
</Note>

## orientation 값 설정

`character_orientation` 은 필수이며 `image` 또는 `video`를 허용합니다.

| 값       | 참조 동영상 길이 |
| ------- | --------- |
| `image` | 3\~10초    |
| `video` | 3\~30초    |

`element_list`을 사용하는 경우 `character_orientation`을 `video`로 설정하세요.

## 모델 및 모드 선택

호환 경로는 `kling-v2-6` 및 `kling-v3`를 허용합니다. 두 모델 값은
모두 다음 모드 값을 허용합니다:

| 모델           | `std` | `pro` |
| ------------ | ----- | ----- |
| `kling-v2-6` | 허용됨   | 허용됨   |
| `kling-v3`   | 허용됨   | 허용됨   |

`model_name`을 생략하면 요청에서 `kling-v2-6`을 사용합니다. `mode`을 생략하면
요청에서 `std`을 사용합니다. `kling-v3` 값은 이 페이지에
설명된 호환 요청 형식을 유지하며, 별도의 Kling 3.0 경로 버전
계약을 선택하지 않습니다.

호환 계약은 고정 출력 해상도를 보장하지 않습니다. 특정 치수가 필요한 경우
반환된 각 동영상을 검사하세요.

`keep_original_sound` 은 `yes` 또는 `no`를 허용합니다. 이 필드를 생략하면 요청에서
`yes`을 사용합니다.

## 작업 흐름

<Steps>
  <Step title="Motion Control 요청 제출">
    소스 이미지, 참조 동영상 및 orientation 값을 전송하세요.
    모델, 모드 및 사운드 값을 선택하거나 문서화된 기본값을 사용하세요. 반환된
    `task_id`을 저장하세요.
  </Step>

  <Step title="작업 폴링">
    다음을 사용하세요: [Kling 작업 가져오기](./individual-queries) 반환된 `task_id`와 함께 사용하세요.
    상태가 `succeed` 또는 `failed` 중 하나가 될 때까지 계속하세요.
  </Step>

  <Step title="결과 저장">
    결과를 즉시 다운로드하여 저장하세요. Kling의 호환 API
    문서에는 생성된 동영상이 30일 후 삭제된다고 명시되어 있습니다. 반환된 URL이
    30일 전체 기간 동안 계속 액세스 가능하다고 가정하지 마세요.
  </Step>
</Steps>

## 선택적 필드

| 필드                 | 구조                                       | 제약 조건                                                        |
| ------------------ | ---------------------------------------- | ------------------------------------------------------------ |
| `prompt`           | 문자열, 최대 2500자                            | 호환 요청 구조의 선택적 텍스트 필드입니다.                                     |
| `callback_url`     | URI 문자열 또는 빈 문자열                         | 콜백 URI가 구성되지 않은 경우 필드를 생략하거나 빈 문자열을 사용하세요.                   |
| `external_task_id` | 계정 내에서 고유한 문자열                           | 작업을 애플리케이션과 연결합니다. CometAPI 쿼리에서 반환되는 `task_id`을 대체하지는 않습니다. |
| `element_list`     | 최대 하나의 `{"element_id": 123}` 객체를 포함하는 배열 | 이 필드는 `character_orientation: "video"`.                      |
| `watermark_info`   | `{"enabled": boolean}`                   | 와만 함께 사용하세요. 호환 워터마크 구조에는 `enabled` 불리언만 포함됩니다.              |

## 콜백 구조

Legacy 콜백 스키마의 구조는 다음과 같습니다:

```json theme={null}
{
  "task_id": "<task_id>",
  "task_status": "succeed",
  "task_status_msg": "",
  "created_at": 1785398400000,
  "updated_at": 1785398460000,
  "final_unit_deduction": "<value>",
  "final_balance_deduction": {
    "quota": "<value>",
    "list_price": "<value>"
  },
  "task_info": {
    "external_task_id": "<your_unique_id>"
  },
  "task_result": {
    "videos": [
      {
        "id": "<video_id>",
        "url": "https://media.example.com/<file_id>.mp4",
        "duration": "6.4"
      }
    ]
  }
}
```

콜백 상태는 `submitted`, `processing`, `succeed` 또는 `failed`일 수 있습니다.
종료 결과 필드는 종료 상태에 대해 반환되는 경우에만 제공됩니다.

## 결과 필드

| 필드                                   | 유형                                        | 설명                                    |
| ------------------------------------ | ----------------------------------------- | ------------------------------------- |
| `task_result.videos[].id`            | 문자열                                       | 생성된 동영상 ID입니다.                        |
| `task_result.videos[].url`           | URI 문자열                                   | 생성된 동영상 전송 URL입니다.                    |
| `task_result.videos[].watermark_url` | URI 문자열                                   | 작업에서 반환되는 경우 워터마크가 적용된 동영상 전송 URL입니다. |
| `task_result.videos[].duration`      | 문자열                                       | 생성된 동영상의 길이(초)입니다.                    |
| `final_unit_deduction`               | 문자열                                       | 작업과 함께 반환되는 최종 단위 차감 값입니다.            |
| `final_balance_deduction`            | `{"quota": string, "list_price": string}` | 작업과 함께 반환되는 최종 잔액 차감 값입니다.            |

작업 상태는 `submitted`, `processing`, `succeed` 또는 `failed`입니다.

<Tip>
  다음 [Kling Motion Control API 참조](https://kling.ai/document-api/api/video/motion-control/legacy)
  및 [Kling 콜백 프로토콜](https://kling.ai/document-api/api/get-started/callbacks)
  에서 API 세부 정보를 확인하세요.
</Tip>


## OpenAPI

````yaml api/openapi/video/kling/post-motion-control.openapi.json POST /kling/v1/videos/motion-control
openapi: 3.1.0
info:
  title: Kling Motion Control API
  version: 1.0.0
  description: >-
    Create a Kling Motion Control task from a character image and a reference
    motion video.
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /kling/v1/videos/motion-control:
    post:
      summary: Create a Kling Motion Control task
      description: >-
        Submit a character image and a reference motion video. The response
        contains a task ID that you can use for status queries.
      operationId: create_kling_motion_control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image_url
                - video_url
                - character_orientation
              properties:
                model_name:
                  type: string
                  description: >-
                    Model ID for this compatible Motion Control request. Omit
                    this field to use `kling-v2-6`. The `kling-v3` value keeps
                    this compatible request shape; it does not select the
                    separate Kling 3.0 path-version contract.
                  enum:
                    - kling-v2-6
                    - kling-v3
                  default: kling-v2-6
                image_url:
                  type: string
                  description: >-
                    Character image as a public URL or a raw Base64 string. Send
                    raw Base64 without a `data:image/...;base64,` prefix;
                    data-URI input is outside the compatible contract. Supported
                    formats are JPG, JPEG, and PNG. The image must be 10 MB or
                    smaller. Its width and height must each be from 300 through
                    65,536 pixels, and its aspect ratio must be between 1:2.5
                    and 2.5:1.
                video_url:
                  type: string
                  format: uri
                  description: >-
                    Public reference motion video URL. Use an MP4 or MOV file
                    that is 100 MB or smaller. The short edge must be at least
                    340 pixels, and the long edge must not exceed 3850 pixels.
                    The video must be at least 3 seconds long. The maximum
                    duration depends on `character_orientation`.
                prompt:
                  type: string
                  maxLength: 2500
                  description: >-
                    Optional text field in the compatible request structure.
                    Maximum 2500 characters.
                keep_original_sound:
                  type: string
                  description: >-
                    Compatible string enum. Accepted values are `yes` and `no`.
                    Omitted requests use `yes`.
                  enum:
                    - 'yes'
                    - 'no'
                  default: 'yes'
                character_orientation:
                  type: string
                  description: >-
                    Required compatible string enum. With `image`, the reference
                    video can be 3 to 10 seconds long. With `video`, the
                    reference video can be 3 to 30 seconds long.
                  enum:
                    - image
                    - video
                mode:
                  type: string
                  description: >-
                    Both compatible models accept `std` and `pro`. Omitted
                    requests use `std`.
                  enum:
                    - std
                    - pro
                  default: std
                callback_url:
                  description: >-
                    Optional callback field in the compatible structure. Provide
                    a URI, or omit the field or send an empty string when no
                    callback URI is configured.
                  oneOf:
                    - type: string
                      format: uri
                    - type: string
                      const: ''
                external_task_id:
                  type: string
                  description: >-
                    Optional ID for correlation in your application. The value
                    must be unique for your account. Store the returned
                    `task_id` for CometAPI status queries.
                element_list:
                  type: array
                  maxItems: 1
                  description: >-
                    Optional compatible Element structure. Provide at most one
                    object, and combine this field only with
                    `character_orientation: video`.
                  items:
                    type: object
                    required:
                      - element_id
                    properties:
                      element_id:
                        type: integer
                        format: int64
                        description: Kling Element ID in the compatible structure.
                    additionalProperties: false
                watermark_info:
                  type: object
                  description: Optional compatible watermark structure.
                  required:
                    - enabled
                  properties:
                    enabled:
                      type: boolean
                      description: Boolean flag in the compatible watermark structure.
                  additionalProperties: false
              example:
                model_name: kling-v3
                image_url: https://your-image-host.example.com/character.png
                video_url: https://your-video-host.example.com/reference-motion.mp4
                prompt: Studio scene.
                keep_original_sound: 'no'
                character_orientation: video
                mode: std
            examples:
              Image URL:
                summary: Use a public character image URL
                value:
                  model_name: kling-v3
                  image_url: https://your-image-host.example.com/character.png
                  video_url: https://your-video-host.example.com/reference-motion.mp4
                  prompt: Studio scene.
                  keep_original_sound: 'no'
                  character_orientation: video
                  mode: std
              Image base64:
                summary: Use a raw Base64 character image
                value:
                  model_name: kling-v3
                  image_url: <your-image-base64>
                  video_url: https://your-video-host.example.com/reference-motion.mp4
                  prompt: Studio scene.
                  keep_original_sound: 'no'
                  character_orientation: video
                  mode: pro
      responses:
        '200':
          description: Task accepted.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                  - data
                properties:
                  code:
                    type: integer
                    description: >-
                      Response code. A value of 0 indicates that the request was
                      accepted.
                  message:
                    type: string
                    description: Response message.
                  data:
                    type: object
                    required:
                      - task_id
                      - task_status
                      - task_info
                      - created_at
                      - updated_at
                    properties:
                      task_id:
                        type: string
                        description: System-generated task ID for status queries.
                      task_status:
                        type: string
                        description: Task state after submission.
                        const: submitted
                      task_status_msg:
                        type: string
                        description: Status detail when returned.
                      task_info:
                        type: object
                        description: Additional task metadata. The object can be empty.
                        additionalProperties: true
                      created_at:
                        type: integer
                        format: int64
                        description: Task creation timestamp in milliseconds.
                      updated_at:
                        type: integer
                        format: int64
                        description: Last task update timestamp in milliseconds.
                example:
                  code: 0
                  message: SUCCEED
                  data:
                    task_id: <task_id>
                    task_status: submitted
                    task_info: {}
                    created_at: 1785398400000
                    updated_at: 1785398400000
      x-codeSamples:
        - lang: Shell
          label: Image URL
          source: |
            curl https://api.cometapi.com/kling/v1/videos/motion-control \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model_name": "kling-v3",
                "image_url": "https://your-image-host.example.com/character.png",
                "video_url": "https://your-video-host.example.com/reference-motion.mp4",
                "prompt": "Studio scene.",
                "keep_original_sound": "no",
                "character_orientation": "video",
                "mode": "std"
              }'
        - lang: Python
          label: Image URL
          source: |
            import os
            import requests

            response = requests.post(
                "https://api.cometapi.com/kling/v1/videos/motion-control",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
                json={
                    "model_name": "kling-v3",
                    "image_url": "https://your-image-host.example.com/character.png",
                    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
                    "prompt": "Studio scene.",
                    "keep_original_sound": "no",
                    "character_orientation": "video",
                    "mode": "std",
                },
            )

            result = response.json()
            print(result.get("code"), result.get("data", {}).get("task_id"))
        - lang: JavaScript
          label: Image URL
          source: |
            const response = await fetch(
              "https://api.cometapi.com/kling/v1/videos/motion-control",
              {
                method: "POST",
                headers: {
                  Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
                  "Content-Type": "application/json",
                },
                body: JSON.stringify({
                  model_name: "kling-v3",
                  image_url: "https://your-image-host.example.com/character.png",
                  video_url: "https://your-video-host.example.com/reference-motion.mp4",
                  prompt: "Studio scene.",
                  keep_original_sound: "no",
                  character_orientation: "video",
                  mode: "std",
                }),
              },
            );

            const result = await response.json();
            console.log(result.code, result.data?.task_id);
        - lang: Shell
          label: Image base64
          source: |
            curl https://api.cometapi.com/kling/v1/videos/motion-control \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -H "Content-Type: application/json" \
              --data-binary @- <<'JSON'
            {
              "model_name": "kling-v3",
              "image_url": "<base64-encoded-png>",
              "video_url": "https://your-video-host.example.com/reference-motion.mp4",
              "prompt": "Studio scene.",
              "keep_original_sound": "no",
              "character_orientation": "video",
              "mode": "pro"
            }
            JSON
        - lang: Python
          label: Image base64
          source: |
            import base64
            import os
            import requests

            with open("character.png", "rb") as image_file:
                image_base64 = base64.b64encode(image_file.read()).decode("ascii")

            response = requests.post(
                "https://api.cometapi.com/kling/v1/videos/motion-control",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
                json={
                    "model_name": "kling-v3",
                    "image_url": image_base64,
                    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
                    "prompt": "Studio scene.",
                    "keep_original_sound": "no",
                    "character_orientation": "video",
                    "mode": "pro",
                },
            )

            result = response.json()
            print(result.get("code"), result.get("data", {}).get("task_id"))
        - lang: JavaScript
          label: Image base64
          source: >
            import { readFile } from "node:fs/promises";


            const imageBase64 = (await
            readFile("character.png")).toString("base64");

            const response = await fetch(
              "https://api.cometapi.com/kling/v1/videos/motion-control",
              {
                method: "POST",
                headers: {
                  Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
                  "Content-Type": "application/json",
                },
                body: JSON.stringify({
                  model_name: "kling-v3",
                  image_url: imageBase64,
                  video_url: "https://your-video-host.example.com/reference-motion.mp4",
                  prompt: "Studio scene.",
                  keep_original_sound: "no",
                  character_orientation: "video",
                  mode: "pro",
                }),
              },
            );


            const result = response.json();

            console.log(result.code, result.data?.task_id);
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication. Use your CometAPI API key.

````