Video brevi con Kling AI tramite API: flusso di lavoro end-to-end per text-to-video con kling-3.0-omni

I video brevi sono un gioco di quantità: i feed premiano gli account che pubblicano ogni giorno, e nessuno può girare, montare e progettare il suono di una clip a mano ogni giorno. kling-3.0-omni/text-to-video è uno dei pochi modelli in grado di coprire l'intera checklist del video breve in una singola chiamata API — output verticale 9:16, movimento cinematografico, sequenze multi-inquadratura e audio nativo sincronizzato — così l'intera pipeline si riduce a "scrivi un prompt, esegui il polling di un task, scarica un .mp4 pronto da pubblicare".

Questa guida percorre l'intero flusso di lavoro end-to-end sull'API hiapi: invio di task asincroni, progettazione di prompt che trattengono gli spettatori mentre scorrono il feed, attivazione dell'audio nativo, scalabilità verso narrazioni multi-inquadratura e generazione batch di varianti. Ogni clip incorporata qui sotto è un output reale, non modificato, al primo tentativo dall'API in produzione — generato per questo articolo, con il prompt esatto e le impostazioni mostrati accanto.

Gli strumenti che userai

kling-3.0-omni/text-to-video (Kling 3.0 Omni di Kuaishou, endpoint text-to-video) gira sull'interfaccia di task asincroni di hiapi. La fatturazione è basata sui secondi di output e dipende dalla risoluzione e dall'attivazione dell'audio nativo. Le seguenti tariffe provengono dalla pagina dei prezzi di hiapi al momento della stesura:

Fascia	Prezzo al secondo	Clip da 5 secondi	Clip da 10 secondi
720p	$0.10	$0.50	$1.00
720p + audio	$0.143	$0.72	$1.43
1080p	$0.129	$0.65	$1.29
1080p + audio	$0.193	$0.97	$1.93
4K	$0.479	$2.40	$4.79

Per i video verticali orientati al feed, il 720p è la scelta onesta: TikTok e Reels ricomprimono comunque tutto, ed è il modo più economico per iterare sui prompt. Riserva 1080p/4K alle clip che montarai anche in altri formati.

Lo schema di input che abbiamo effettivamente verificato in questo articolo: prompt (stringa), duration (secondi interi — abbiamo eseguito 5 e 10 secondi), resolution (720p / 1080p / 4K), aspect_ratio (9:16 per il verticale) e sound (booleano, disattivato per impostazione predefinita). Un comportamento che vale la pena conoscere prima di costruirci sopra: quando ometti sound, l'.mp4 restituito non ha alcuna traccia audio — non una traccia silenziosa, ma nessuna traccia. Se la tua pipeline di montaggio a valle si aspetta un flusso audio in ogni file, imposta sempre sound: true oppure gestisci esplicitamente i file senza traccia.

Invia → esegui il polling → scarica: il ciclo di vita del task

Tutto passa attraverso POST /v1/tasks. Invia il task, ricevi immediatamente l'ID del task, esegui il polling finché non è completato, poi scarica l'output. Una clip da 5 secondi a 720p di solito viene renderizzata in pochi minuti.

Invio con 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-omni/text-to-video",
    "input": {
      "prompt": "Vertical short-form video. A barista in a sunlit specialty coffee bar pours a perfect rosetta latte art in one smooth motion, steam rising, morning light through the window, shallow depth of field, crisp photoreal detail, subtle slow push-in.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "9:16"
    }
  }'

La risposta arriva immediatamente:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWZYC1VKGV2CCSBK6AY9862H"}, "message": "success"}

Poi esegui il polling di GET /v1/tasks/{taskId} finché status non è success (o fail), e scarica output[0].url. Di seguito uno script helper Python completo — è il pattern effettivo che abbiamo usato per generare ogni clip di questa guida:

import json, subprocess, time, os

API = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

def submit(input_fields: dict) -> str:
    payload = {"model": "kling-3.0-omni/text-to-video", "input": input_fields}
    out = subprocess.run(
        ["curl", "-s", "-X", "POST", API,
         "-H", f"Authorization: Bearer {TOKEN}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, timeout=70).stdout
    return json.loads(out)["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 900) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        out = subprocess.run(
            ["curl", "-s", f"{API}/{task_id}",
             "-H", f"Authorization: Bearer {TOKEN}"],
            capture_output=True, text=True, timeout=40).stdout
        task = json.loads(out)["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(8)
    raise TimeoutError(task_id)

task_id = submit({
    "prompt": "...",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16",
})
task = wait(task_id)
video_url = task["output"][0]["url"]
subprocess.run(["curl", "-s", "-o", "clip.mp4", video_url], timeout=120)

Un dettaglio operativo importante in produzione: l'output[0].url che ricevi è un link firmato a scadenza (con tempo di scadenza). Scarica i byte immediatamente dopo il successo del task e salvali nel tuo bucket o CDN — non salvare mai l'URL grezzo del task in un database o CMS.

Progettare prompt per un hook di 3 secondi

Il successo di un video breve dipende da ciò che accade sullo schermo nel primo secondo. Il pattern di prompt che funziona ripetutamente per gli hook verticali: un soggetto, un'azione continua e soddisfacente, luce descritta esplicitamente e movimento di camera espresso in linguaggio cinematografico. Ecco il prompt esatto dell'esempio curl sopra, e la clip che ha prodotto:

Vertical short-form video. A barista in a sunlit specialty coffee bar pours a
perfect rosetta latte art in one smooth motion, steam rising, morning light
through the window, shallow depth of field, crisp photoreal detail, subtle
slow push-in.

Output reale — kling-3.0-omni/text-to-video, 5 secondi @ 720p, 9:16, senza audio. Prima generazione, non modificata.

Il ruolo di ogni elemento:

• "Vertical short-form video" (video breve verticale) all'inizio ancora le decisioni di composizione, non solo le proporzioni in pixel — il modello compone per lo schermo del telefono.
• Un'unica azione continua ("pours ... in one smooth motion", cioè "versa ... con un unico movimento fluido") dà al modello un singolo arco da renderizzare, anziché introdurre tagli casuali.
• "Subtle slow push-in" (leggera spinta in avanti lenta) è una vera istruzione di camera. Parole emotive vaghe ("dynamic", "engaging") fanno improvvisare il modello; il vocabolario cinematografico lo mantiene in carreggiata.
• La luce merita una frase intera ("morning light through the window", cioè "luce del mattino attraverso la finestra") — la luce è la differenza tra una "clip AI" e una vera ripresa sul set.

Audio nativo: imposta sound: true e descrivi il paesaggio sonoro

La funzione distintiva di Kling 3.0 Omni è l'audio nativo sincronizzato — il modello renderizza una traccia sonora che corrisponde all'immagine, e per contenuti food, ASMR e di strada è gran parte della ritenzione. Bisogna fare due cose insieme: impostare "sound": true nell'input (fatturato alla tariffa +audio, $0.143/secondo a 720p) e descrivere l'audio nel prompt proprio come descrivi l'immagine:

Vertical short-form video. Close-up of a street food vendor's wok at night:
diced garlic and chili hit sizzling oil with a burst of steam, flames lick up
the wok's edge as the vendor tosses noodles in rhythmic flips, neon signs
glowing bokeh in the background. Handheld feel, appetizing, high energy.
Native audio: loud sizzle, wok clangs, distant street chatter.

Output reale — kling-3.0-omni/text-to-video, 5 secondi @ 720p, 9:16, sound: true. Alza il volume: il crepitio e i colpi del wok sono generati dal modello e sincronizzati con il movimento di saltare in padella.

Il pattern con suffisso "Native audio:" — una breve lista di due o tre suoni chiave separati da virgole — supera in modo affidabile descrizioni in prosa come "with realistic sound effects" (con effetti sonori realistici). Nomina i suoni e il modello li sincronizzerà con gli eventi visivi corrispondenti.

Abbiamo verificato il confine di fatturazione sugli output reali con ffprobe: le clip inviate senza sound contengono solo un flusso video H.264, mentre le clip con sound: true portano un'ulteriore traccia audio AAC. Paghi il sovrapprezzo audio solo per le clip che richiedono audio.

Narrazione multi-inquadratura in un unico prompt

L'altra funzione distintiva di Omni sono le sequenze multi-inquadratura: puoi scrivere tagli espliciti in una singola generazione, invece di unire tre clip separate. Numera le inquadrature nel prompt e assegna all'intera sequenza una color grade condivisa, così sembra un montaggio e non un incidente:

Vertical short-form video, three-shot sequence. Shot 1: a young woman in a
yellow rain jacket steps out of a subway exit into light rain, opens a clear
umbrella. Shot 2: close-up of her boots splashing through a neon-reflecting
puddle in slow motion. Shot 3: she stops at a food cart, smiles as warm steam
drifts past, city lights bokeh behind. Cohesive teal-and-amber grade,
cinematic handheld energy. Native audio: soft rain, city ambience, distant
traffic hum.

Output reale — kling-3.0-omni/text-to-video, 10 secondi @ 720p, 9:16, sound: true. Tre inquadrature scriptate, una sola generazione: $1.43.

Calcola circa tre secondi per inquadratura — una durata di 10 secondi si adatta a una storia in tre battute. Un'ancora ricorrente (la giacca da pioggia gialla) è la chiave per mantenere l'identità coerente tra i tagli; fornisci a ogni prompt multi-inquadratura una costante visiva ben riconoscibile, altrimenti il soggetto si sposta tra le inquadrature.

Produzione in batch: un template, molte varianti

L'economia diventa interessante su scala. Una settimana di post giornalieri è un template di prompt con slot variabili, inviati in parallelo — i task vengono renderizzati in parallelo, quindi un batch si completa più o meno nel tempo di una clip. Abbiamo preso il template dell'hook del latte e sostituito il soggetto:

Vertical short-form video. A ceramic bowl of matcha being whisked into a vivid
green froth with a bamboo whisk, in a sunlit specialty tea bar, steam rising,
morning light through the window, shallow depth of field, crisp photoreal
detail, subtle slow push-in.

Output reale — stesso template della clip del latte, con una sola variabile cambiata. 5 secondi @ 720p, 9:16: $0.50.

La spinta in avanti, la luce della finestra e la profondità di campo ridotta restano identiche — esattamente la coerenza visiva che vuoi per un account. Nel codice, il batch significa inviare prima di attendere:

TEMPLATE = ("Vertical short-form video. {subject}, in a sunlit specialty {venue}, "
            "steam rising, morning light through the window, shallow depth of field, "
            "crisp photoreal detail, subtle slow push-in.")

VARIANTS = [
    {"subject": "A barista pouring a perfect rosetta latte art in one smooth motion", "venue": "coffee bar"},
    {"subject": "A ceramic bowl of matcha being whisked into a vivid green froth with a bamboo whisk", "venue": "tea bar"},
    {"subject": "A croissant being pulled apart to reveal steaming, glossy layers", "venue": "bakery"},
]

task_ids = [submit({
    "prompt": TEMPLATE.format(**v),
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16",
}) for v in VARIANTS]          # all rendering in parallel

clips = [wait(tid) for tid in task_ids]

Pianificazione dei costi a 720p: 30 clip hook mute da 5 secondi al mese costano $15; lo stesso mese con audio nativo costa $21.45. Anche con un calendario aggressivo — clip audio da 10 secondi ogni giorno — sono solo $42.90/mese, meno di un'ora del tempo di un montatore video. Esegui il polling dei risultati man mano che arrivano e tratta lo stato fail di un task come un nuovo tentativo solo per quella variante, non per l'intero batch.

Tutto il contenuto di questo articolo è costato $3.15 in generazione video: quattro clip, 25 secondi di materiale, tutte al primo tentativo.

Passi successivi

Ora hai il ciclo completo: invia un task 9:16, esegui il polling, scarica l'.mp4 e scala con i template. Alcuni suggerimenti per i passi successivi:

• Ottieni una chiave API e il riferimento completo degli endpoint nella documentazione di hiapi — il ciclo di vita del task sopra è identico per ogni modello video della piattaforma.
• Prima di pianificare batch grandi, controlla le tariffe correnti al secondo per tutte le fasce nella pagina dei prezzi.
• Se per questo caso d'uso devi scegliere tra modelli, abbiamo eseguito lo stesso flusso di lavoro per video brevi su un modello economico in Short-Form Video with seedance-2.0-mini — utile come baseline prezzo/qualità rispetto a Kling.

Inizia con una clip di prova da $0.50 del tuo soggetto, conserva gli elementi del prompt che hanno superato il test del feed, poi trasforma il template in un batch di task nella pagina del modello kling-3.0-omni/text-to-video.