Crea un'attività Kling Motion Control

POST

kling

videos

motion-control

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"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

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 la richiesta Motion Control

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.

Interroga l'attività

Usa l’endpoint Ottieni un’attività Kling con il task_id restituito. Continua finché lo stato non diventa succeed o failed.

Memorizza il risultato

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:

{
  "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"
      }
    ]
  }
}

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 e Protocollo di callback Kling per i dettagli dell’API.

Autorizzazioni

Authorization

string

header

obbligatorio

Bearer authentication. Use your CometAPI API key.

Corpo

application/json

image_url

string

obbligatorio

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

string<uri>

obbligatorio

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.

character_orientation

enum<string>

obbligatorio

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.

Opzioni disponibili:

image,

video

model_name

enum<string>

predefinito:kling-v2-6

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.

Opzioni disponibili:

kling-v2-6,

kling-v3

prompt

string

Optional text field in the compatible request structure. Maximum 2500 characters.

Maximum string length: 2500

keep_original_sound

enum<string>

predefinito:yes

Compatible string enum. Accepted values are yes and no. Omitted requests use yes.

Opzioni disponibili:

yes,

no

mode

enum<string>

predefinito:std

Both compatible models accept std and pro. Omitted requests use std.

Opzioni disponibili:

std,

pro

callback_url

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.

external_task_id

string

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

object[]

Optional compatible Element structure. Provide at most one object, and combine this field only with character_orientation: video.

Maximum array length: 1

Show child attributes

watermark_info

object

Optional compatible watermark structure.

Show child attributes

Risposta

200 - application/json

Task accepted.

code

integer

obbligatorio

Response code. A value of 0 indicates that the request was accepted.

message

string

obbligatorio

Response message.

data

object

obbligatorio

Show child attributes

Ultima modifica il 31 luglio 2026

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"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

Moderazione dei contenuti

Chiavi API

Crea un'attività Kling Motion Control

File multimediali richiesti

Imposta il valore dell’orientamento

Scegli il modello e la modalità

Flusso dell’attività

Campi facoltativi

Struttura del callback

Campi del risultato

Autorizzazioni

Corpo

Risposta

​File multimediali richiesti

​Imposta il valore dell’orientamento

​Scegli il modello e la modalità

​Flusso dell’attività

​Campi facoltativi

​Struttura del callback

​Campi del risultato

Autorizzazioni

Corpo

Risposta

File multimediali richiesti

Imposta il valore dell’orientamento

Scegli il modello e la modalità

Flusso dell’attività

Campi facoltativi

Struttura del callback

Campi del risultato