Blog

Tutoriale

Come chiamare kling-3.0-omni/transformation tramite l'API HiAPI: guida con curl e Python

Una panoramica completa delle richieste funzionanti per il trasferimento di stile video su HiAPI

Nov 12, 2026
Immagine di copertina del blog HiAPI: su uno sfondo blu indaco scuro, frecce larghe annidate procedono a gradini, con il bordo color albicocca che delinea il flusso del segnale.
In questa pagina

Funzionalità e casi d'uso dell'endpoint transformation

kling-3.0-omni/transformation è un endpoint di trasferimento di stile video su HiAPI. Gli si forniscono due cose: un video sorgente e un'istruzione di stile in linguaggio naturale. Restituisce un nuovo video in cui il contenuto del video sorgente viene preservato ma presentato nello stile visivo richiesto.

Puoi considerarlo come una fase di post-produzione nascosta dietro una chiamata HTTP. Non devi addestrare modelli, mantenere cluster GPU o gestire file di checkpoint. Descrivi l'effetto visivo che desideri, indichi un video e l'endpoint produce il rendering.

Scenari adatti a questo endpoint

  • Aggiungere stile a materiale esistente. Hai già un girato e vuoi che appaia come animazione, acquerello, grana pellicola, claymation o un altro effetto. Contenuto e movimento provengono dal tuo video; l'endpoint modifica la texture superficiale.
  • Mantenere uno stile coerente in batch. Poiché lo stile è espresso come istruzione, puoi riutilizzare lo stesso prompt su molti video sorgente ottenendo una serie di risultati stilisticamente coerenti.
  • Prototipare lo sviluppo dello stile. I team creativi possono iterare a basso costo sulle direzioni stilistiche prima di investire in flussi di produzione più onerosi.

Scenari non adatti

  • Devi generare un video da zero (text-to-video è un'altra attività).
  • Devi fare editing, montaggio o compositing frame per frame preciso. La trasformazione rimodella solo lo stile, non esegue editing.
  • Il tuo materiale sorgente è solo audio o una singola immagine statica.

Il resto di questa guida illustra passo dopo passo la struttura della richiesta, una chiamata curl eseguibile, la versione Python corrispondente e i dettagli operativi relativi a output 4K e attività di lunga durata.

Analisi della richiesta: video sorgente, istruzione di stile e opzioni di output

Una richiesta di trasformazione non è complessa. Prima di scrivere codice, scomponila in tre gruppi di campi: video sorgente, istruzioni e impostazioni di output.

Video sorgente

L'endpoint deve poter accedere al tuo input. In pratica, passi un URL che la piattaforma può recuperare, oppure un identificatore restituito dalla fase di caricamento file di HiAPI. La regola pratica è: il file sorgente deve essere accessibile dal server, non dal tuo laptop. Percorsi localhost o file dietro la tua VPN non funzionano.

Mantieni il formato sorgente conservativo: usa container e codec ampiamente supportati. Se il tuo video è generato da una pipeline particolare e non supera la validazione, ricodificalo prima in un MP4 H.264 standard. Questo passaggio da solo risolve gran parte degli errori di input.

Istruzione di stile

È la descrizione in linguaggio naturale dell'effetto visivo desiderato. È il campo più influente della richiesta e quello su cui vale più la pena lavorare.

  • Descrivi la resa visiva, non il contenuto. Il contenuto proviene dal video; dire al modello ciò che è già sullo schermo spreca solo budget del prompt.
  • Siispecifico riguardo a mezzo e texture: «animazione in claymation con impronte digitali visibili» comunica molto più di «animazione».
  • Quando è importante, specifica cosa conservare: «mantieni i volti riconoscibili, movimento di camera invariato».
  • Mantieniti entro un paragrafo focalizzato. Prompt lunghi e contraddittori tendono a mediare verso risultati scialbi.

Opzioni di output

Le impostazioni di output controllano risoluzione e altri dettagli di consegna. La decisione principale è richiedere 4K o risoluzione standard. Risoluzioni più alte consumano più calcolo e richiedono più tempo, quindi vanno considerate una scelta consapevole e non un default. In generale l'endpoint viene eseguito come attività asincrona, quindi la tua richiesta di solito restituisce un riferimento a un job che dovrai interrogare o attendere, anziché il file finito.

Mappa prima i tuoi input su questi tre gruppi di campi, e il corpo JSON effettivo della richiesta diventerà chiaro.

Una richiesta curl funzionante da zero

Il modo più rapido per verificare la comprensione è una chiamata minimale. La forma seguente invia un URL di video sorgente e un'istruzione di stile, e richiede un risultato a risoluzione standard. Sostituisci i valori segnaposto con i tuoi.

curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": "Converti in animazione acquerello disegnata a mano, bordi sfumati morbidi, texture della carta visibile, palette calda e limitata. Mantieni i volti e il movimento di camera.",
    "resolution": "1080p"
  }'

Cosa fa ciascuna parte

  • Il percorso URL specifica l'endpoint. Deve essere esatto; un errore di battitura qui restituisce un errore di routing, non di validazione.
  • L'header Authorization trasporta la tua chiave HiAPI. Esportala come variabile d'ambiente invece di incollarla nella cronologia della shell.
  • video_url è il video sorgente. Deve essere recuperabile dal server.
  • prompt è l'istruzione di stile. È il campo che modificherai di più.
  • resolution è l'impostazione di output. Inizia da una risoluzione bassa durante l'iterazione e alzala quando l'effetto è definito.

Interpretare la risposta

Una risposta riuscita ti restituisce un oggetto job. Registra l'identificatore del job e qualsiasi campo di stato:

{
  "id": "job_abc123",
  "status": "queued"
}

I nomi esatti dei campi vanno letti dalla risposta reale, non presunti. L'abitudine importante è la stessa in qualsiasi linguaggio: analizza il JSON, estrai l'id del job e considera il video completato come qualcosa che arriverà più tardi. Non scrivere codice che presuppone che la prima risposta contenga già un file riproducibile.

La stessa richiesta in Python

La versione Python è la chiamata curl, con il corpo JSON espresso come dizionario. Usare requests mantiene il codice leggibile e le dipendenze leggere.

import os
import time
import requests

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

payload = {
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": (
        "Converti in animazione acquerello disegnata a mano, bordi sfumati morbidi, "
        "texture della carta visibile, palette calda e limitata. Mantieni i volti e il movimento di camera."
    ),
    "resolution": "1080p",
}

resp = requests.post(
    f"{BASE}/kling-3.0-omni/transformation",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("inviato", job_id, job.get("status"))

Eseguire polling finché il job non è completato

Poiché il rendering è asincrono, avvolgi l'attesa in un ciclo con un numero limitato di tentativi e una pausa tra i controlli. Usa una pausa sufficientemente ampia per non martellare l'API e imposta un limite massimo di attesa per evitare che un job bloccato sospenda il tuo worker.

def wait_for_job(job_id, max_attempts=60, interval=10):
    for _ in range(max_attempts):
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error") or "job failed")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish in time")

result = wait_for_job(job_id)
print(result.get("output") or result)

Renderlo sicuro per la produzione

  • Leggi il percorso dell'endpoint e la route di polling dalla documentazione delle risposte API, invece di codificare ipotesi che potrebbero cambiare.
  • Registra l'id del job al momento dell'invio. Se qualcosa va storto a valle, è il tuo unico punto di aggancio.
  • Considera failed e timeout come esiti distinti. Un job fallito di solito indica un problema di parametri; un timeout di solito indica un problema di capacità o durata.

Gestire output 4K e attività di lunga durata

Due variabili dominano il comportamento operativo di questo endpoint: risoluzione di output e durata dell'input. Pianifica esplicitamente per entrambe.

Output 4K

Il 4K è una decisione di consegna, non un default. Ogni pixel di output consuma calcolo, e il salto relativo dalla risoluzione standard al 4K è notevole. Flusso di lavoro sensato:

  1. Itera l'istruzione di stile a risoluzione più bassa. La qualità del prompt è indipendente dalla risoluzione, quindi ottimizza prima l'effetto a basso costo.
  2. Blocca prompt e video sorgente.
  3. Esegui di nuovo una volta in 4K per la consegna.

Evita di generare varianti 4K in un ciclo serrato mentre aggiusti la formulazione: è il modo più comune di sprecare budget in rendering che finirai per scartare.

Attività di lunga durata

Video sorgente più lunghi richiedono più tempo per la trasformazione, e l'endpoint restituisce un riferimento a un job anziché un file finito. Progetta il tuo client attorno a questa realtà:

  • Non bloccare mai una richiesta web sul rendering. Invia, memorizza l'id del job e restituisci subito il controllo al chiamante.
  • Separa invio e recupero. Un worker con coda e polling è più robusto dell'attesa inline e sopravvive ai riavvii del processo.
  • Persisti lo stato del job. Se un worker muore a metà polling, il job non scompare; puoi riprendere dall'id memorizzato.
  • Se il tuo account supporta i webhook, usali, mantenendo il polling come percorso di fallback.
  • Imposta un budget totale di attesa che rifletta il video più lungo che prevedi, non un numero arbitrario.

Un pattern pratico

Dividi i video sorgente più lunghi della durata tipica in segmenti, trasformali uno per uno e ricomponi i risultati. Questo riduce il tempo di attesa per singola operazione, ti permette di ritentare solo un segmento invece dell'intero rendering e rende i fallimenti poco costosi. Verifica che i confini dei segmenti non taglino movimenti rapidi, altrimenti le giunture saranno evidenti.

Diagnosticare i guasti comuni

La maggior parte dei guasti rientra in tre categorie: video sorgente illeggibile, parametri rifiutati, oppure job che non si completa mai. Isola la categoria del problema prima di cambiare qualsiasi cosa.

Errori di upload e accesso alla sorgente

Sintomo: l'invio fallisce, oppure il job fallisce quasi subito per errore di input.

  • URL non accessibile pubblicamente. Provalo da una macchina esterna alla tua rete. Gli URL firmati che scadono tra invio e recupero sono i colpevoli tipici.
  • Formato non supportato. Ricodifica in MP4 H.264 standard e riprova.
  • File troncato o corrotto. Scaricalo tu stesso e riproducilo dall'inizio alla fine.
  • Richiesta troppo grande. Se stai inviando i byte del file inline anziché un URL, passa al flusso di caricamento e usa l'identificatore restituito.

Errori di parametri

Sintomo: risposta 4xx al momento dell'invio.

  • JSON malformato. Controlla il corpo con un linter. Virgole finali e virgolette non escape sono errori comuni nelle chiamate curl scritte a mano.
  • Nome o tipo di campo errato. Confronta con lo schema di richiesta corrente; passare la risoluzione come numero quando ci si aspetta una stringa fallisce.
  • Prompt vuoto o contraddittorio. Se l'istruzione non descrive nulla, o richiede stili mutuamente esclusivi, aspettati output deboli o un rifiuto. Riscrivila attorno a una direzione visiva chiara.
  • Chiave API mancante o non valida. Controlla il valore dell'header e se la chiave è valida per questo endpoint.

Timeout e job bloccati

Sintomo: il job resta in coda o in esecuzione oltre il tuo budget di attesa, oppure il tuo client si arrende.

  • Distingui il timeout del client dal fallimento del job. Un timeout HTTP breve al momento dell'invio non significa che il job non sia partito; controlla se esiste un id del job prima di reinviare, altrimenti potresti duplicare il rendering.
  • Input lunghi e output 4K allungano i tempi di esecuzione. Se vai in timeout ripetutamente, abbassa la risoluzione o accorcia il video per confermare che il flusso funzioni, poi risalì gradualmente.
  • Se il job segnala failed, leggi il messaggio di errore prima di ritentare. Ripetere ciecamente errori deterministici di parametri non fa che moltiplicare i costi.

Sequenza di debug efficace

Parti dalla richiesta più piccola possibile: un video breve a risoluzione standard e un prompt di una frase. Se funziona, reintroduci uno per uno il prompt reale, la durata reale e infine il 4K, cambiando una sola variabile alla volta. Il passo che fallisce ti dice qual è la causa.

Compromessi tra costo e latenza da pianificare

Una volta che la richiesta funziona, le decisioni rimanenti sono operative. Tre leve influenzano contemporaneamente costo e latenza, e interagiscono tra loro.

Risoluzione

La risoluzione di output è la leva singola più importante. La fatturazione è legata al lavoro di rendering eseguito, e output a risoluzione più alta significa più lavoro. Regola pratica: itera a bassa risoluzione, consegna ad alta risoluzione. Non far mai girare esperimenti di stile in 4K.

Durata dell'input

Video sorgente più lunghi significano più frame da trasformare, quindi più calcolo e più tempo reale. Se il tuo caso d'uso lo consente, trasforma una selezione breve invece del montaggio integrale, oppure suddividi il materiale lungo e trasforma solo le parti che devono essere elaborate.

Nuovi tentativi

A meno che il fallimento non avvenga prima che il job inizi, ogni nuovo tentativo è un rendering completo. Ecco perché la sequenza di debug conta: valida i parametri a basso costo prima di spendere per il rendering. Previeni gli invii duplicati registrando l'id del job e controllandolo prima di reinviare dopo un timeout del client.

Elaborazione batch e parallelismo

Job paralleli riducono il tempo reale ma non il costo totale, e possono raggiungere i limiti di concorrenza. Per il lavoro batch, una coda moderata con parallelismo controllato di solito è meglio di un fan-out. Ti mantiene sotto i limiti di frequenza, rende i fallimenti facili da ritentare singolarmente e offre una curva di spesa prevedibile.

Checklist di budget

  • Fissa il prompt a bassa risoluzione prima di qualsiasi rendering di consegna.
  • Metti in cache gli output completati; non rirerenderizzare gli stessi input.
  • Imposta aspettative di spesa per job e per batch, e avvisa quando un batch le supera.
  • Traccia la durata dei job in relazione a risoluzione e durata dell'input, così da prevedere il nuovo lavoro dalle esecuzioni passate.
  • Tratta il 4K come ultimo passo della pipeline, non come modalità interattiva.

I prezzi di questo endpoint sono elencati sul sito HiAPI, quindi controlla lì le tariffe correnti prima di pianificare la dimensione dei batch. Fai funzionare prima la richiesta minima, poi scala con consapevolezza risoluzione e durata: questo ordine mantiene prevedibili sia la latenza sia la fattura.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API