> ## 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.
# Crea un'attività Kling Motion Control
> Crea un'attività Kling Motion Control da un'immagine del personaggio e da un video di movimento di riferimento con il percorso CometAPI compatibile.
Usa questo endpoint per creare un'attività Motion Control da un'immagine del personaggio e da un
video di riferimento.
Questa pagina descrive il percorso Motion Control compatibile. Kling Video 3.0
Motion Control utilizza un contratto API separato.
## File multimediali richiesti
`image_url` accetta un URL pubblico o una stringa Base64 non elaborata.
* Usa un'immagine JPG, JPEG o PNG di dimensioni pari o inferiori a 10 MB.
* Imposta ogni dimensione dell'immagine tra 300 e 65.536 pixel.
* Usa un rapporto di aspetto compreso tra 1:2,5 e 2,5:1.
* Invia Base64 come stringa codificata non elaborata senza un
`data:image/...;base64,` prefisso.
* Mostra un solo personaggio senza ostruzioni, con un'inquadratura del corpo che corrisponda al movimento
di riferimento.
`video_url` accetta un URL MP4 o MOV pubblico.
* Usa un video di dimensioni pari o inferiori a 100 MB.
* Assicurati che il lato corto sia di almeno 340 pixel.
* Assicurati che il lato lungo non superi i 3850 pixel.
* Usa una ripresa continua con un solo personaggio visibile.
* Evita tagli, cambi di telecamera e movimenti eccessivamente rapidi.
Rispetta i limiti di durata e controlla il `task_status` terminale. Un
HTTP 200 esterno o una risposta `code: 0` confermano la risposta della query, non un
risultato di generazione riuscito.
## Imposta il valore dell'orientamento
`character_orientation` è obbligatorio e accetta `image` o `video`.
| Valore | Durata del video di riferimento |
| ------- | ------------------------------- |
| `image` | 3–10 secondi |
| `video` | 3–30 secondi |
Se usi `element_list`, imposta `character_orientation` su `video`.
## Scegli il modello e la modalità
Il percorso compatibile accetta `kling-v2-6` e `kling-v3`. Entrambi i valori del modello
accettano entrambi i valori della modalità:
| Modello | `std` | `pro` |
| ------------ | --------- | --------- |
| `kling-v2-6` | Accettato | Accettato |
| `kling-v3` | Accettato | Accettato |
Se ometti `model_name`, la richiesta usa `kling-v2-6`. Se ometti `mode`,
la richiesta usa `std`. Il valore `kling-v3` mantiene la struttura della richiesta compatibile
descritta in questa pagina; non seleziona il contratto separato di Kling 3.0 basato sulla versione del percorso
.
Il contratto compatibile non garantisce una risoluzione di output fissa. Controlla
ogni video restituito se la tua applicazione richiede dimensioni specifiche.
`keep_original_sound` accetta `yes` o `no`. Se ometti questo campo, la
richiesta usa `yes`.
## Flusso dell'attività
Invia l'immagine di origine, il video di riferimento e il valore di orientamento. Seleziona un
modello, una modalità e un valore audio oppure usa i rispettivi valori predefiniti documentati. Memorizza il
`task_id` restituito.
Usa l'endpoint [Ottieni un'attività Kling](./individual-queries) con il `task_id` restituito.
Continua finché lo stato non diventa `succeed` o `failed`.
Scarica e archivia tempestivamente il risultato. L'API compatibile di Kling
indica nella documentazione che i video generati vengono eliminati dopo 30 giorni. Non
fare affidamento sul fatto che l'URL restituito rimanga accessibile per tutti i 30 giorni.
## Campi facoltativi
| Campo | Struttura | Vincolo |
| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `prompt` | Stringa, massimo 2500 caratteri | Campo di testo facoltativo nella struttura della richiesta compatibile. |
| `callback_url` | Stringa URI o stringa vuota | Ometti il campo o usa una stringa vuota quando non è configurato alcun URI di callback. |
| `external_task_id` | Stringa univoca per il tuo account | Collega l'attività alla tua applicazione. Non sostituisce l'`task_id` restituito per le query CometAPI. |
| `element_list` | Array con al massimo un oggetto `{"element_id": 123}` | Combina questo campo solo con `character_orientation: "video"`. |
| `watermark_info` | `{"enabled": boolean}` | La struttura della filigrana compatibile contiene solo il booleano `enabled`. |
## Struttura del callback
Lo schema di callback Legacy ha la seguente struttura:
```json theme={null}
{
"task_id": "",
"task_status": "succeed",
"task_status_msg": "",
"created_at": 1785398400000,
"updated_at": 1785398460000,
"final_unit_deduction": "",
"final_balance_deduction": {
"quota": "",
"list_price": ""
},
"task_info": {
"external_task_id": ""
},
"task_result": {
"videos": [
{
"id": "",
"url": "https://media.example.com/.mp4",
"duration": "6.4"
}
]
}
}
```
Lo stato del callback può essere `submitted`, `processing`, `succeed` o `failed`.
I campi del risultato terminale sono presenti solo quando vengono restituiti per lo stato terminale.
## Campi del risultato
| Campo | Tipo | Descrizione |
| ------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------- |
| `task_result.videos[].id` | Stringa | ID del video generato. |
| `task_result.videos[].url` | Stringa URI | URL di consegna del video generato. |
| `task_result.videos[].watermark_url` | Stringa URI | URL di consegna del video con filigrana quando l'attività ne restituisce uno. |
| `task_result.videos[].duration` | Stringa | Durata del video generato in secondi. |
| `final_unit_deduction` | Stringa | Valore finale di deduzione delle unità restituito con l'attività. |
| `final_balance_deduction` | `{"quota": string, "list_price": string}` | Valori finali di deduzione del saldo restituiti con l'attività. |
Lo stato dell'attività è `submitted`, `processing`, `succeed` o `failed`.
Consulta il [Riferimento API di Kling Motion Control](https://kling.ai/document-api/api/video/motion-control/legacy)
e [Protocollo di callback Kling](https://kling.ai/document-api/api/get-started/callbacks)
per i dettagli dell'API.
## 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:
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_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": "",
"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.
````