> ## 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. # Create a Kling motion-control video > Create a Kling motion-control task from a character image and a reference motion video. Use `POST /motion-control/{model}` to animate a character image with the movement from a reference video. The request creates an asynchronous task. ## Choose a model | Model ID | Resolution | `settings.audio` | | ----------- | --------------- | ----------------- | | `kling-3.0` | `720p`, `1080p` | `original`, `off` | | `kling-2.6` | `720p`, `1080p` | `original`, `off` | Use the character image and reference video as publicly accessible URLs. Set `settings.audio` to `original` to retain audio from the reference video, or `off` for silent output. The image must be JPG or PNG, at most 50 MB, and at least 300 pixels on each edge. Use an MP4 or MOV reference video of at least 3 seconds and at most 100 MB. With `character_orientation: image`, the video can be up to 10 seconds; with `video`, it can be up to 30 seconds. ## Request parameters | Field | Required | Description | | -------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------- | | `model` | Yes | Model ID in the URL: `kling-3.0` or `kling-2.6`. | | `contents` | Yes | Array containing one `image` item and one `video` item. Add a `prompt` item to describe the scene. | | `contents[].type` | Yes | `image` for the character, `video` for the motion reference, or `prompt` for text guidance. | | `contents[].url` | For image and video items | Public URL for the character image or reference motion video. | | `contents[].text` | For a `prompt` item | Required text guidance for the generated scene. | | `settings.resolution` | No | Output resolution: `720p` or `1080p`. If omitted, the request uses `720p`. | | `settings.character_orientation` | Yes | `image` uses the character orientation from the image; `video` uses the reference video. | | `settings.audio` | No | `original` retains reference audio; `off` disables it. If omitted, the request uses `off`. | | `options.callback_url` | No | HTTPS URL that receives task status callbacks. | | `options.external_task_id` | No | Your own task identifier for correlation; retain the returned `data.id` for queries. | | `options.watermark_info.enabled` | No | Set to `true` to request a watermark. | To animate a character image, send this request body to `POST /motion-control/kling-2.6`. Replace the media URLs with your own accessible files when using your own character and motion: ```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" } } ``` The response returns an `id` for the asynchronous task: ```json theme={null} { "code": 0, "message": "SUCCEED", "data": { "id": "example-task-id", "status": "submitted" } } ``` Use the `data.id` value with [Get a Kling task](./tasks) until the task completes. Read the finished video URL from the task's `outputs` array. Store the video in your own storage if you need durable access. The OpenAPI panel contains matching Shell, Python, and JavaScript requests. For more input details, see the [Kling motion-control API reference](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 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 MotionControlSettings: type: object required: - character_orientation description: Output resolution, reference orientation, and audio settings. 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' default: 'off' description: >- `original` retains the reference video's audio. `off` makes silent output. additionalProperties: false TaskOptions: type: object description: Optional task notification and identification settings. 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. ````