Come creare video brevi con kling-3.0/motion-control sull'API hiapi

Se hai mai provato a far eseguire a un personaggio in un video generato un movimento specifico — non "ballare", ma questa particolare danza in questa particolare clip — sai che le opzioni abituali sono pessime: rotoscoping manuale fotogramma per fotogramma, riaddestrare un modello di movimento, o arrendersi e accettare qualsiasi cosa il prompt testuale ti restituisca. kling-3.0/motion-control salta tutto questo. Gli dai un'immagine di un personaggio e un video di riferimento, e trasferisce i movimenti e le espressioni del riferimento sul tuo personaggio — senza rigging scheletrico, senza keyframe, senza tuta motion capture.

Questo articolo percorre un vero flusso di lavoro per video brevi: prima si trasforma la foto di un autista in una breve clip di riferimento, poi si usa quella clip tramite motion-control per animare l'immagine di un personaggio completamente diverso. Ogni richiesta qui sotto è una chiamata reale all'API /v1/tasks di hiapi, ogni asset è stato generato durante la stesura di questo articolo (niente preso in prestito dalle gallerie demo dei fornitori), e ogni prezzo è stato recuperato in tempo reale dall'endpoint dei prezzi di hiapi.

Cosa fa esattamente kling-3.0/motion-control

Il modello accetta due input:

• image_url — un singolo ritratto di un personaggio (il "target"). Questo determina chi appare nell'output.
• video_url — una clip di riferimento per il movimento, da 3 a 30 secondi. Questo determina cosa fa.

L'output è un video in cui il personaggio target esegue i movimenti e le espressioni facciali del video di riferimento, renderizzato a 720p o 1080p. Non accetta prompt testuali, durata o rapporto d'aspetto — la composizione dell'output segue direttamente la clip di riferimento, e la lunghezza dell'output segue la lunghezza della clip di input (il nostro riferimento di 3 secondi ha restituito un output di 3,03 secondi).

Questo contratto ristretto a soli due input è ciò che lo rende utile per i contenuti video brevi: non ti servono attrezzature motion capture per dare una performance credibile a una mascotte di brand, a un personaggio prodotto o a un avatar stilizzato — ti serve solo qualsiasi video di una persona che fa il movimento che desideri.

Cosa ti serve

• Una chiave API di hiapi (Authorization: Bearer <key>)
• Un'immagine di un personaggio accessibile pubblicamente via HTTPS (non il tuo target — il tuo personaggio guida)
• Una seconda immagine di un personaggio, come vero target che vuoi animare
• ffmpeg/ffprobe se vuoi estrarre localmente il fotogramma di copertina o controllare la durata della clip, come in questo articolo

Demo reale: una clip di movimento, due personaggi diversi

Il punto chiave di motion-control è che il video di riferimento e il personaggio finale non devono coincidere. Per dimostrarlo, questa demo usa tre passaggi di generazione:

1. Il ritratto di un autista, animato in una breve clip di riferimento:

Quel ritratto è stato trasformato in una clip di movimento di 3 secondi a 480p tramite grok-imagine-1.5/image-to-video — un modo rapido ed economico per creare una clip di riferimento da un'immagine statica, invece di cercare una clip già pronta:

2. Un personaggio target completamente diverso — stesso movimento, aspetto totalmente differente:

3. Dai entrambi a motion-control. Il venditore esegue esattamente la stessa giravolta e sguardo all'indietro del corriere:

Questo è l'intero flusso di lavoro: genera (o procurati) qualsiasi clip di movimento ti piaccia, punta motion-control verso un'immagine di personaggio completamente estranea, e ottieni quel personaggio che esegue il movimento. Per una pipeline di video brevi, questo significa che una libreria di movimenti di riferimento può animare un numero infinito di personaggi, senza dover rigirare o rifare l'animazione di riferimento ogni volta.

La richiesta minima funzionante (curl)

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/target-character.png",
      "video_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/motion-reference.mp4",
      "resolution": "720p"
    }
  }'

Risposta (attività creata, ancora in elaborazione):

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "pending"
  },
  "success": true
}

Esegui polling finché non è completato:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Nella nostra esecuzione, una clip di 3 secondi a 720p ha impiegato circa 2,3 minuti dall'inizio alla fine (lo stato ha ciclato su handling una dozzina di volte circa prima di passare a success) — quando progetti il ciclo di polling, prevedi qualche minuto, non qualche secondo. Risposta finale:

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "success",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M4CWNSYA7RB637YJ2QZMHMMS-0.mp4",
        "storage": "temp",
        "expireAt": 1792039027
      }
    ]
  },
  "success": true
}

Quel output[0].url è un link temporaneo — expireAt è un timestamp Unix, valido circa 24 ore nel nostro test. Scaricalo subito e ri-ospitalo; non collegarti direttamente ad esso da nulla che pubblichi.

Lo stesso flusso in Python

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def create_motion_control_task(image_url: str, video_url: str, resolution: str = "720p") -> str:
    resp = requests.post(
        API_BASE,
        headers=HEADERS,
        json={
            "model": "kling-3.0/motion-control",
            "input": {
                "image_url": image_url,
                "video_url": video_url,
                "resolution": resolution,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, timeout_s: int = 600, poll_every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = create_motion_control_task(
        image_url="https://your-cdn.example.com/target-character.png",
        video_url="https://your-cdn.example.com/motion-reference.mp4",
        resolution="720p",
    )
    output_url = wait_for_result(task_id)

    video_bytes = requests.get(output_url, timeout=120).content
    with open("motion-control-output.mp4", "wb") as f:
        f.write(video_bytes)
    print(f"saved {len(video_bytes)} bytes")

Niente di complicato — crea un'attività, esegui polling su GET /v1/tasks/{taskId} a intervalli, scarica output[0].url nel momento in cui diventa success, e ri-ospitalo tu stesso prima che il link temporaneo scada.

I parametri realmente validati da motion-control

Lo schema è rigoroso — qualsiasi cosa al di fuori di questi tre campi viene rifiutata, ed è utile saperlo in anticipo piuttosto che scoprirlo per tentativi ed errori:

Campo	Obbligatorio	Descrizione
image_url	Sì	URL HTTPS pubblico, personaggio target
video_url	Sì	URL HTTPS pubblico, riferimento di movimento da 3 a 30 secondi
resolution	No (ha un valore predefinito, ma conviene impostarlo)	"720p" o "1080p" — determina anche la fascia di prezzo

Campi che potresti aspettarti da altri modelli video — duration, aspect_ratio, prompt — vengono rifiutati con un errore di schema:

{
  "code": 1,
  "message": "input: Object { input } has unexpected additional properties: duration, aspect_ratio",
  "success": false
}

È per design: la lunghezza e la composizione dell'output ereditano completamente dal video di riferimento, quindi duration/aspect_ratio non hanno nulla da controllare. Se vuoi un output più lungo o con una composizione diversa, ritaglia o ricomponi la clip di riferimento prima di inviarla, invece di modificare la richiesta.

Prezzi: a consumo per secondo di output, non per richiesta

Direttamente dall'endpoint dei prezzi di hiapi:

Risoluzione	Prezzo
720p	$0,10 / secondo di output
1080p	$0,172 / secondo di output

La fatturazione è guidata dalla durata effettiva dell'output (estimated_seconds), che riflette la lunghezza della tua clip di riferimento — non un costo fisso per richiesta. Il nostro riferimento di 3 secondi ha prodotto un output di 3,03 secondi a 720p, per un costo di circa $0,30. Una clip di riferimento di 10 secondi a 1080p si avvicina invece a $1,72. Se la usi in blocco nel tuo calendario editoriale, la leva realmente regolabile è la lunghezza della clip di riferimento: clip più brevi costano meno e riescono comunque a veicolare una performance di movimento completa per i formati brevi (Reels, TikTok, Shorts), dove 3–8 secondi sono spesso l'intera clip.

Note per la produzione

• Scegli con intenzione la composizione della clip guida. L'output eredita il rapporto d'aspetto, la distanza della camera e il ritmo del video di riferimento — un riferimento in primo piano resta un output in primo piano, indipendentemente da come è ritagliata l'immagine del personaggio target.
• Le espressioni marcate si trasferiscono meglio di quelle sottili. Una giravolta netta, un saluto o un'inclinazione della testa nel riferimento appaiono in modo affidabile sul personaggio target; micro-espressioni molto sottili e naturali sono più difficili da riconoscere e trasferire per il modello.
• Riusa una clip di riferimento su molti personaggi. Poiché video_url e image_url sono completamente indipendenti, il pattern più efficiente in una pipeline di contenuti è: crea prima una piccola libreria di movimenti di riferimento, poi usa la stessa clip con molte immagini di personaggi diverse.
• Gli URL di output temporanei scadono in fretta. expireAt è di solito intorno a un giorno — scarica e ri-ospitala subito, invece di rimandare il download a più tardi.
• L'elaborazione non è istantanea. In questo test, una clip di 3 secondi a 720p ha impiegato più di due minuti dall'inizio alla fine; pianifica il tuo ciclo di polling e qualsiasi automazione a valle su base minuti (non sui secondi tipici delle chiamate di text-to-image).

Contenuti correlati

• Pagina del modello kling-3.0/motion-control
• Prezzi di hiapi
• Documentazione dell'API di hiapi

Hai una clip di riferimento e un personaggio da abbinare? Ottieni una chiave dalla pagina dei prezzi, poi punta la richiesta curl qui sopra ai tuoi image_url/video_url — l'intero ciclo qui sopra è pronto da copiare e incollare.

Domande frequenti

Posso usare qualsiasi video come riferimento di movimento? Va bene qualsiasi video con un interprete umano (o simile a un umano) chiaramente visibile, purché sia accessibile pubblicamente via HTTPS e lungo da 3 a 30 secondi. Non deve contenere il tuo personaggio target — è proprio questo il senso del modello.

L'output mantiene lo sfondo del video di riferimento? No — l'aspetto del personaggio, compreso l'ambiente suggerito dall'immagine target, viene mantenuto; il video di riferimento fornisce i movimenti e le espressioni, non il contenuto della scena.

Perché la mia richiesta è stata rifiutata con "unexpected additional properties"? Lo schema accetta solo image_url, video_url e resolution. Campi come duration, aspect_ratio o prompt non fanno parte degli input di questo modello e restituiscono immediatamente un 400 — rimuovili dal payload.

Quanto richiede un'attività motion-control? Prevedi qualche minuto per clip. Il nostro esempio di 3 secondi a 720p ha impiegato circa 2,3 minuti dalla creazione dell'attività all'output success scaricabile.

Posso controllare la risoluzione dell'output indipendentemente dal prezzo? No — resolution è sia un'impostazione di qualità dell'output sia un selettore della fascia di prezzo: "720p" viene fatturato a $0,10/secondo di output, "1080p" a $0,172/secondo di output.