Tutoriale
Come usare kling-3.0/motion-control tramite l'API HiAPI: esempi curl e Python
In questa pagina
A cosa serve kling-3.0/motion-control e quando sceglierlo
Il motion control è una capacità della generazione video: si fornisce al modello un video di riferimento e questo guida il movimento, il ritmo e la composizione dell'output, invece di descrivere l'azione solo tramite un prompt testuale. Quando si usa kling-3.0/motion-control sull'API HiAPI, il video di riferimento è l'input principale: ancora il modo in cui gli oggetti si muovono, mentre gli altri parametri modellano il contenuto generato attorno a quel movimento.
Quando il movimento stesso è il punto difficile, conviene scegliere questo modello. Scenari tipici adatti:
- Hai un breve video e vuoi riprodurne il movimento di camera o l'azione del soggetto con contenuti diversi.
- Ti serve un movimento prevedibile, invece di un risultato text-to-video che si affida alla fortuna del prompt testuale.
- Stai costruendo una pipeline in cui il movimento è un asset riutilizzabile tra più generazioni, quindi deve essere un input e non una frase descrittiva.
Se ti serve solo text-to-video e non hai un riferimento di movimento, il motion control aggiunge solo passaggi di caricamento e vincoli di input più rigidi, senza vantaggi. Allo stesso modo, se il video di riferimento è molto lungo o la composizione è instabile, aspettati più tentativi. Il resto di questa guida presuppone che tu abbia stabilito che il motion control è lo strumento adatto e che desideri un'integrazione affidabile e riproducibile.
Prerequisiti e configurazione dell'endpoint
Prima della prima chiamata, prepara tre cose.
1. Chiave API
Crea una chiave nella console del tuo account HiAPI.ai e salvala in una variabile d'ambiente, non nel codice sorgente:
export HIAPI_API_KEY="your_api_key_here"
Ogni richiesta la invia come bearer token: Authorization: Bearer $HIAPI_API_KEY.
2. Convenzione dell'URL di base
Tutte le chiamate HiAPI condividono lo stesso URL di base e lo stesso prefisso di percorso con versione. Metti l'URL di base nella configurazione, così da poter cambiare ambiente senza modificare i punti di chiamata:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. Identificatore del modello
Il modello si seleziona per richiesta tramite il campo model, usando l'identificatore esatto kling-3.0/motion-control. Non codificarlo in più punti: passalo come costante, così in futuro cambiare modello richiederà una sola riga.
Ti serve inoltre una posizione ospitata da cui l'API possa recuperare il video di riferimento. Di solito si usa un URL firmato con scadenza; assicurati che sia accessibile senza header personalizzati o cookie.
Con questi tre elementi pronti, il resto del lavoro riguarda la struttura della richiesta e il ciclo di vita dell'attività.
Fornire il video di riferimento e i parametri di movimento
Una richiesta di motion control si divide concettualmente in due parti: la sorgente del movimento (il video di riferimento) e le impostazioni di generazione (ciò che il modello deve produrre).
Video di riferimento
Il video di riferimento va nel corpo della richiesta come URL, non come byte grezzi nel payload JSON. Due regole pratiche:
- Usa un URL valido per tutta la durata in cui l'attività è in coda ed elaborata. Gli URL firmati che scadono in anticipo sono una causa comune di attività che falliscono pochi minuti dopo l'invio.
- Mantieni il video breve e con inquadratura stabile. Materiale di riferimento troppo lungo, molto mosso o con tagli frequenti fornisce al modello un segnale di movimento ambiguo.
Se il materiale è in uno storage privato, genera l'URL firmato al momento dell'invio con una validità sufficientemente lunga, non al momento del caricamento.
Parametri di movimento e output
Parametri solitamente impostati insieme al video di riferimento:
- Un prompt testuale che descriva il contenuto desiderato, che deve essere guidato dal movimento di riferimento.
- Impostazioni di proporzioni e durata dell'output, così che il video generato si adatti al tuo punto di pubblicazione.
- Qualsiasi impostazione di intensità o aderenza al movimento esposta dal modello, per bilanciare la fedeltà al riferimento e la libertà del prompt.
Raggruppa questi parametri in un piccolo oggetto di configurazione esplicito nel client, invece di spargerli tra gli argomenti delle funzioni. Così è facile registrare esattamente cosa è stato inviato, che è il materiale di debug più utile per questo modello.
Infine, valida prima dell'invio: l'URL di riferimento restituisce un content type multimediale, il prompt non è vuoto e tutte le impostazioni numeriche rientrano nei limiti della documentazione. Un controllo locale costa millisecondi; un'attività asincrona rifiutata costa un round trip e confusione.
Attività asincrona: invio, polling e lettura del risultato
Il motion control non restituisce il video nella risposta di invio, ma un'attività che devi monitorare. Progetta il client fin dall'inizio attorno a questo ciclo di vita.
Passo 1 — Invio
Esegui un POST dell'attività all'endpoint del modello. Un invio riuscito restituisce un identificatore di attività. Salva subito quell'ID in modo persistente: è il tuo unico handle per operare sull'attività, usato sia nel polling sia nelle richieste di supporto.
Passo 2 — Polling
Esegui un GET dello stato dell'attività con quell'ID. Il campo di stato ti dice in quale dei tre casi ti trovi:
- In attesa o in coda: accettata, non ancora avviata. Continua ad attendere.
- In elaborazione o in esecuzione: in corso. Continua ad attendere, ma con una strategia di backoff.
- Stato terminale: riuscita o fallita. Interrompi il polling.
Il ciclo di polling deve controllare esplicitamente gli stati terminali, non solo la presenza del campo di output. Un'attività fallita non ha risultato, e trattare "nessun risultato" come "ancora in esecuzione" porta a un ciclo infinito.
Passo 3 — Lettura del risultato
In caso di successo, la risposta contiene la posizione dell'output, di solito l'URL del video generato. Scaricalo prontamente nel tuo storage: un asset generato dietro un URL temporaneo non va considerato disponibile in modo permanente.
Regole per il polling
Due regole lo rendono affidabile in produzione:
- Applica un backoff tra i polling (parti da uno o due secondi, poi incrementa), invece di martellare l'endpoint.
- Limita il tempo di attesa totale ed esponi il timeout come errore ritentabile, invece di bloccare indefinitamente il thread di lavoro.
Registra per ogni esecuzione l'ID dell'attività, i parametri inviati e lo stato finale. Quando qualcosa va storto, quel log risponde alla maggior parte delle domande prima ancora che tu debba chiedere ad altri.
Richiesta curl eseguibile
Di seguito il flusso completo nella shell. Invia l'attività, estrae l'ID e poi esegue il polling finché l'attività non raggiunge uno stato terminale.
#!/usr/bin/env bash
set -euo pipefail
BASE="$HIAPI_BASE_URL"
MODEL="kling-3.0/motion-control"
# 1) Invia l'attività
SUBMIT=$(curl -sS -X POST "$BASE/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0/motion-control",
"prompt": "una barchetta di carta che galleggia lungo una strada cittadina sotto la pioggia, atmosfera cinematografica",
"reference_video_url": "https://your-bucket.example.com/refs/pan-left.mp4",
"duration": 5,
"aspect_ratio": "16:9"
}')
echo "$SUBMIT"
TASK_ID=$(echo "$SUBMIT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "task: $TASK_ID"
# 2) Esegui il polling fino allo stato terminale
while true; do
STATUS_JSON=$(curl -sS "$BASE/v1/videos/generations/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY")
STATUS=$(echo "$STATUS_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
echo "status: $STATUS"
case "$STATUS" in
succeeded) echo "$STATUS_JSON"; break ;;
failed|cancelled) echo "$STATUS_JSON" >&2; exit 1 ;;
esac
sleep 3
done
Due note sull'adattamento di questo script. Primo, mantieni l'identificatore del modello e il percorso dell'endpoint in variabili, così lo script resta leggibile. Secondo, l'analisi sopra non usa jq ma solo Python, perché Python è disponibile quasi ovunque; se preferisci jq, puoi sostituirlo. In entrambi i casi il comportamento chiave è lo stesso: estrarre l'ID dell'attività dalla risposta di invio e poi interrogarne lo stato finché non compare un valore terminale.
La stessa richiesta (versione Python)
Il client Python seguente corrisponde al flusso curl, ma con un ciclo di polling più robusto: backoff quasi esponenziale, timeout complessivo e gestione esplicita di ogni stato terminale.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-3.0/motion-control"
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
TERMINAL = {"succeeded", "failed", "cancelled"}
def submit_job(prompt: str, reference_video_url: str, duration: int = 5) -> str:
payload = {
"model": MODEL,
"prompt": prompt,
"reference_video_url": reference_video_url,
"duration": duration,
"aspect_ratio": "16:9",
}
r = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
r.raise_for_status()
return r.json()["id"]
def wait_for_job(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/videos/generations/{task_id}",
headers=HEADERS,
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in TERMINAL:
return data
time.sleep(delay)
delay = min(delay * 1.5, 15.0)
raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task_id = submit_job(
prompt="una barchetta di carta che galleggia lungo una strada cittadina sotto la pioggia, atmosfera cinematografica",
reference_video_url="https://your-bucket.example.com/refs/pan-left.mp4",
)
print("submitted:", task_id)
result = wait_for_job(task_id)
if result["status"] == "succeeded":
print("output:", result.get("output"))
else:
print("job did not succeed:", result)
Aspetti da conservare nell'adattamento: l'insieme degli stati terminali, il backoff con limite massimo e le funzioni separate di invio e attesa. In un servizio reale le separerai in due processi — invio dal gestore delle richieste, memorizzazione dell'ID, polling da parte di un worker — così le attività lente non bloccano mai la risposta HTTP.
Punti di errore comuni e come eseguirne il debug
La maggior parte dei problemi di integrazione con kling-3.0/motion-control ricade in poche categorie. Controlla in ordine.
Errori di autenticazione e modello
Un 401 significa quasi sempre che il bearer token manca, è troncato o proviene dall'ambiente sbagliato. Un errore di modello non trovato significa che la stringa di model non corrisponde esattamente — è un identificatore separato da barra, quindi un ordine di caratteri errato o spazi superflui falliscono in silenzio nella configurazione e generano un errore esplicito nell'API.
Video di riferimento non disponibile
L'attività viene accettata ma fallisce dopo qualche minuto perché non riesce a recuperare l'URL di riferimento. Cause in ordine di frequenza: l'URL firmato scade prima dell'elaborazione; l'URL richiede un header di autenticazione che il servizio non invia; l'URL restituisce HTML (pagina di login o di errore) invece di un video. Prova l'URL con un normale curl dall'esterno della tua rete e verifica il content type.
Formato dei parametri errato o fuori intervallo
Impostazioni di durata e proporzioni fuori dai limiti della documentazione vengono rifiutate all'invio, e questo è un bene — ottieni subito l'errore. Valida in locale, così un refuso non richiede un round trip per essere scoperto.
Difetti nel polling
Due problemi classici: il ciclo controlla solo il campo di output e mai failed, causando un ciclo infinito; e il polling in un ciclo stretto senza pause, che porta a essere limitati per frequenza. Aggiungi il controllo esplicito degli stati terminali e il backoff, e includi sempre l'ID dell'attività nella segnalazione degli errori, così da poter interrogare l'attività invece di ricrearla.
URL del risultato scaduto
Hai generato il video ma hai salvato solo l'URL temporaneo dell'output. Scarica subito l'output nel tuo storage dopo il successo dell'attività; considera l'URL restituito come un handle per il recupero, non come archiviazione persistente.
All'inizio di ogni sessione di debug, registra il corpo esatto della richiesta e il JSON della risposta grezza. Quasi tutti i problemi sopra sono visibili in questi due materiali. Quando sei pronto ad approfondire, consulta gli altri modelli video e il riferimento degli endpoint nella documentazione di HiAPI.ai, mantenendo la stessa forma del client "prima invia, poi esegui il polling".
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business