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
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
Authorizationtrasporta 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
failede 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:
- Itera l'istruzione di stile a risoluzione più bassa. La qualità del prompt è indipendente dalla risoluzione, quindi ottimizza prima l'effetto a basso costo.
- Blocca prompt e video sorgente.
- 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.
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