> ## 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 모션 제어 비디오 만들기

> 캐릭터 이미지와 참조 모션 비디오로 Kling 모션 제어 작업을 만듭니다.

`POST /motion-control/{model}`을 사용하여 참조 비디오의 움직임으로 캐릭터 이미지에 애니메이션을 적용합니다. 요청은 비동기 작업을 생성합니다.

## 모델 선택

| 모델 ID | 해상도 | `settings.audio` |
| - | - | - |
| `kling-3.0` | `720p`, `1080p` | `original`, `off` |
| `kling-2.6` | `720p`, `1080p` | `original`, `off` |

캐릭터 이미지와 참조 비디오는 공개적으로 액세스할 수 있는 URL로 사용하세요. 참조 비디오의 오디오를 유지하려면 `settings.audio`을 `original`로 설정하고, 무음 출력을 생성하려면 `off`로 설정하세요.

이미지는 JPG 또는 PNG 형식이어야 하며, 최대 50MB이고 각 변의 길이가 최소 300픽셀이어야 합니다. 참조 비디오는 길이 3초 이상, 크기 100MB 이하의 MP4 또는 MOV를 사용하세요. `character_orientation: image`에서는 비디오 길이가 최대 10초이고, `video`에서는 최대 30초입니다.

## 요청 파라미터

| 필드 | 필수 | 설명 |
| - | - | - |
| 경로 `model` | 예 | URL의 모델 ID: `kling-3.0` 또는 `kling-2.6`. 요청 본문에 추가하지 마세요. |
| `contents` | 예 | `image` 항목 하나와 `video` 항목 하나를 포함하는 배열입니다. 장면을 설명하려면 `prompt` 항목을 추가하세요. |
| `contents[].type` | 예 | `image` 캐릭터에는 `video`, 모션 참조에는 `prompt`, 텍스트 안내에는 |
| `contents[].url` | 이미지 및 비디오 항목의 경우 | 캐릭터 이미지 또는 참조 모션 비디오의 공개 URL입니다. |
| `contents[].text` | `prompt` 항목의 경우 | 생성할 장면에 필요한 텍스트 안내입니다. |
| `settings.resolution` | 아니요 | 출력 해상도: `720p` 또는 `1080p`. 생략하면 요청은 `720p`. |
| `settings.character_orientation` | 예 | `image` 이미지의 캐릭터 방향을 사용하며, `video`은 참조 비디오를 사용합니다. |
| `settings.audio` | 아니요 | 참조 오디오를 유지하려면 `original`로 설정하고, 비활성화하려면 `off`로 설정하세요. 값을 명시적으로 설정하세요. |
| `options.callback_url` | 아니요 | 작업 상태 콜백을 수신하는 HTTPS URL입니다. |
| `options.external_task_id` | 아니요 | 연결을 위한 자체 작업 식별자입니다. 조회를 위해 반환된 `data.id`을 유지하세요. |
| `options.watermark_info.enabled` | 아니요 | 워터마크를 요청하려면 `true`로 설정하세요. |

캐릭터 이미지에 애니메이션을 적용하려면 이 요청 본문을 `POST /motion-control/kling-2.6`에 전송하세요. 자체 캐릭터와 모션을 사용할 때는 미디어 URL을 액세스 가능한 자체 파일로 바꾸세요:

```json theme={null}
{
  "contents": [
    {
      "type": "prompt",
      "text": "The character performs the dance shown in the reference video."
    },
    {
      "type": "image",
      "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png"
    },
    {
      "type": "video",
      "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4"
    }
  ],
  "settings": {
    "resolution": "720p",
    "character_orientation": "video",
    "audio": "off"
  }
}
```

응답은 비동기 작업의 `id`을 반환합니다:

```json theme={null}
{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "id": "example-task-id",
    "status": "submitted"
  }
}
```

`data.id` 값을 다음과 함께 사용하세요 [Kling 작업 가져오기](https://apidoc.cometapi.com/ko/api/video/kling/model-routes/tasks.md) 작업이 완료될 때까지 사용하세요. 완료된 비디오 URL은 작업의 `outputs` 배열에서 읽으세요. 지속적인 액세스가 필요하면 비디오를 자체 스토리지에 저장하세요.

OpenAPI 패널에는 이에 대응하는 Shell, Python, JavaScript 요청이 포함되어 있습니다. 추가 입력 세부 정보는 다음을 참조하세요. [Kling 모션 제어 API 참조](https://kling.ai/document-api/api/video/3-0-omni/motion-control).


## OpenAPI

````yaml api/openapi/video/kling/model-routes/post-motion-control.openapi.json POST /motion-control/{model}
openapi: 3.1.0
info:
  title: Kling motion-control model routes
  version: 1.0.0
  description: Create a Kling motion-control video task with a model ID in the URL.
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /motion-control/{model}:
    post:
      summary: Create a Kling motion-control task
      description: >-
        Animate a character image with movement from a reference video. Save the
        returned task ID for status queries.
      operationId: createKlingModelRouteMotionControl
      parameters:
        - name: model
          in: path
          required: true
          description: Kling motion-control model ID.
          schema:
            type: string
            enum:
              - kling-3.0
              - kling-2.6
          example: kling-2.6
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MotionControlRequest'
            example:
              contents:
                - type: prompt
                  text: >-
                    The character performs the dance shown in the reference
                    video.
                - type: image
                  url: >-
                    https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png
                - type: video
                  url: >-
                    https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4
              settings:
                resolution: 720p
                character_orientation: video
                audio: 'off'
      responses:
        '200':
          description: Task created. Store `data.id` for a `GET /tasks` query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              example:
                code: 0
                message: SUCCEED
                data:
                  id: example-task-id
                  status: submitted
      x-codeSamples:
        - lang: Shell
          label: Create task
          source: |
            curl https://api.cometapi.com/motion-control/kling-2.6 \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -H "Content-Type: application/json" \
              --data-binary @- <<'JSON'
            {
              "contents": [
                {
                  "type": "prompt",
                  "text": "The character performs the dance shown in the reference video."
                },
                {
                  "type": "image",
                  "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png"
                },
                {
                  "type": "video",
                  "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4"
                }
              ],
              "settings": {
                "resolution": "720p",
                "character_orientation": "video",
                "audio": "off"
              }
            }
            JSON
        - lang: Python
          label: Create task
          source: |
            import os
            import requests

            response = requests.post(
                "https://api.cometapi.com/motion-control/kling-2.6",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
                json={
                    "contents": [
                        {
                            "type": "prompt",
                            "text": "The character performs the dance shown in the reference video.",
                        },
                        {
                            "type": "image",
                            "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png",
                        },
                        {
                            "type": "video",
                            "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4",
                        },
                    ],
                    "settings": {
                        "resolution": "720p",
                        "character_orientation": "video",
                        "audio": "off",
                    },
                },
            )
            response.raise_for_status()
            result = response.json()
            print(result["data"]["id"])
        - lang: JavaScript
          label: Create task
          source: |
            const response = await fetch(
              "https://api.cometapi.com/motion-control/kling-2.6",
              {
                method: "POST",
                headers: {
                  Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
                  "Content-Type": "application/json",
                },
                body: JSON.stringify({
                  "contents": [
                    {
                      "type": "prompt",
                      "text": "The character performs the dance shown in the reference video."
                    },
                    {
                      "type": "image",
                      "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png"
                    },
                    {
                      "type": "video",
                      "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4"
                    }
                  ],
                  "settings": {
                    "resolution": "720p",
                    "character_orientation": "video",
                    "audio": "off"
                  }
                }),
              },
            );
            if (!response.ok) throw new Error(`HTTP ${response.status}`);
            const result = await response.json();
            console.log(result.data.id);
components:
  schemas:
    MotionControlRequest:
      type: object
      required:
        - contents
        - settings
      properties:
        contents:
          type: array
          minItems: 2
          description: >-
            Send a character image and motion reference video. Add a prompt item
            for scene guidance.
          items:
            $ref: '#/components/schemas/ContentItem'
          allOf:
            - contains:
                type: object
                required:
                  - type
                properties:
                  type:
                    const: image
                    description: Character image input role.
              minContains: 1
              maxContains: 1
            - contains:
                type: object
                required:
                  - type
                properties:
                  type:
                    const: video
                    description: Motion reference video input role.
              minContains: 1
              maxContains: 1
        settings:
          $ref: '#/components/schemas/MotionControlSettings'
        options:
          $ref: '#/components/schemas/TaskOptions'
      additionalProperties: false
      description: >-
        Motion-control request fields exposed by the CometAPI route. The model
        ID is a path parameter, not a body field.
    SubmitResponse:
      type: object
      required:
        - code
        - message
        - data
      properties:
        code:
          type:
            - integer
            - string
          description: Result code. `0` indicates task creation.
        message:
          type: string
          description: Result message.
        msg:
          type: string
          description: Additional result message, when included.
        data:
          type: object
          description: Task identification and submission status.
          required:
            - id
            - status
          properties:
            id:
              type: string
              description: System task ID for a `GET /tasks` query.
            status:
              type: string
              enum:
                - submitted
                - processing
                - succeeded
                - failed
              description: Task status.
    ContentItem:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - prompt
            - image
            - video
          description: >-
            Input role: text guidance, character appearance image, or motion
            reference video.
        text:
          type: string
          maxLength: 2500
          description: Text prompt, required when `type` is `prompt`.
        url:
          type: string
          description: >-
            Required for image and video items. The image accepts a public URL
            or Base64 JPG/PNG; the motion video accepts a public MP4/MOV URL.
      allOf:
        - if:
            properties:
              type:
                const: prompt
                description: Text-prompt input role.
          then:
            required:
              - text
          else:
            required:
              - url
      additionalProperties: false
      description: Content input fields exposed by the CometAPI route.
    MotionControlSettings:
      type: object
      required:
        - character_orientation
      description: >-
        Output resolution, reference orientation, and explicitly selected audio
        behavior.
      properties:
        character_orientation:
          type: string
          enum:
            - image
            - video
          description: >-
            `image` follows the character orientation in the image and allows a
            reference video up to 10 seconds. `video` follows the reference
            video and allows up to 30 seconds.
        resolution:
          type: string
          enum:
            - 720p
            - 1080p
          default: 720p
          description: Output resolution.
        audio:
          type: string
          enum:
            - original
            - 'off'
          description: >-
            Set `original` to retain the reference video's audio or `off` to
            make a silent output. Set the value explicitly.
      additionalProperties: false
    TaskOptions:
      type: object
      description: Optional task fields exposed by the CometAPI route.
      properties:
        callback_url:
          type: string
          format: uri
          description: HTTPS URL that receives task status callbacks.
        external_task_id:
          type: string
          description: >-
            Your own task identifier, unique within your account. The response
            still returns the system task ID.
        watermark_info:
          type: object
          description: Watermark setting for the generated output.
          required:
            - enabled
          properties:
            enabled:
              type: boolean
              description: Set to `true` to request a watermarked result.
          additionalProperties: false
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Authenticate with your CometAPI API key.

````

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