Come si usa l'API di Kling 3.0 Omni? Quattro endpoint operativi in 5 minuti

TL;DR

• Kling 3.0 Omni è il modello video tuttofare di Kling; su HiAPI è suddiviso in quattro endpoint: text-to-video, image-to-video, reference-to-video e video transformation. Apri la pagina del modello per generare online; i nuovi utenti ricevono 200 crediti alla registrazione.
• Fatturazione al secondo: da $0.10/s a 720p, da $0.129/s a 1080p, $0.479/s a 4K; l'audio e il video di riferimento hanno un prezzo separato.
• L'API usa sempre lo stesso endpoint /v1/tasks, cambiando solo model e input. I curl e gli esempi Python qui sotto si possono copiare ed eseguire subito.

Cosa fa ciascuno dei quattro endpoint?

ID modello	Input	Ideale per
kling-3.0-omni/text-to-video	prompt	Creare una scena da zero
kling-3.0-omni/image-to-video	1 frame iniziale, oppure frame iniziale + frame finale	Animare un'immagine
kling-3.0-omni/reference-to-video	da 1 a 7 immagini di riferimento, con possibilità di aggiungere 1 video di riferimento	Bloccare persone, prodotti o seguire il movimento di camera di un video di riferimento
kling-3.0-omni/transformation	1 video originale	Mantenere movimento di camera e azioni, cambiando scena e stile

Tutti e quattro gli endpoint permettono di scegliere la risoluzione 720p, 1080p, 4k. Text-to-video e reference-to-video consentono di impostare durata (3–15 secondi), formato (16:9, 9:16, 1:1) e audio (audio); image-to-video consente di impostare durata e audio, mentre il formato segue il frame iniziale; video transformation accetta solo prompt, video originale e risoluzione, la durata e il formato seguono il video originale e non viene generato audio. Text-to-video, image-to-video e reference-to-video supportano anche i multi-shot intelligenti (prefer_multi_shots), e tutti e quattro gli endpoint supportano i soggetti riutilizzabili (elements, scrivendo @nome nel prompt).

La barchetta di carta in una notte di pioggia da 3 secondi a 720p qui sotto è stata generata direttamente con un solo prompt:

A paper boat drifts down a rain-soaked city gutter at dusk, neon signs reflecting and rippling on the water; the camera glides low beside it as raindrops splash around. Cinematic, shallow depth of field, smooth tracking motion.

Genera con questo prompt →

Due percorsi per iniziare

Prova online (senza scrivere codice)

1. Apri la pagina del modello corrispondente (ad esempio text-to-video), registrati o accedi.
2. Incolla il prompt, scegli durata, risoluzione, formato e attiva l'audio se necessario.
3. Clicca su genera e scarica il video una volta prodotto.

Chiamata API

1. Crea una API Key nella console.
2. Invia con POST https://api.hiapi.ai/v1/tasks, che restituisce taskId.
3. Controlla lo stato con GET /v1/tasks/{taskId}; quando status è success, scarica da output[0].url.

curl: text-to-video

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/text-to-video",
    "input": {
      "prompt": "A paper boat drifts down a rain-soaked city gutter at dusk, neon signs reflecting on the water.",
      "duration": 5,
      "resolution": "720p",
      "audio": false,
      "aspect_ratio": "16:9"
    }
  }'

Python: invio, polling, download

import os, time, requests

H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, **inp):
    r = requests.post("https://api.hiapi.ai/v1/tasks",
                      json={"model": model, "input": inp}, headers=H)
    task_id = r.json()["data"]["taskId"]
    while True:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(10)

url = generate(
    "kling-3.0-omni/image-to-video",
    prompt="Morning fog slowly lifts over the harbor, camera slowly pushes in along the dock.",
    image_urls=["https://your-cdn.example.com/harbor.jpg"],
    duration=5, resolution="720p",
)
open("clip.mp4", "wb").write(requests.get(url).content)

Come si scrivono gli altri tre endpoint?

Image-to-video: passa 1 immagine in image_urls come frame iniziale, oppure 2 immagini come frame iniziale e finale; il formato di output segue il frame iniziale.

Morning fog slowly lifts over the harbor as the fishing boats rock gently on the water; the low sun breaks through the haze and glints on the wet pier, camera slowly pushes in along the dock. Cinematic, calm, photorealistic.

Genera con questo prompt →

Reference-to-video: image_urls è obbligatorio (da 1 a 7 immagini, JPG/PNG, massimo 50MB ciascuna e lato più corto non inferiore a 300px); è possibile aggiungere 1 video_urls come riferimento per il movimento di camera (MP4/MOV, 3–15.5 secondi, massimo 200MB). Il seguente usa l'immagine del frame iniziale della barchetta di carta come riferimento del soggetto e il video della notte di pioggia qui sopra come riferimento per il movimento di camera, spostando la barchetta di carta su un ruscello nel bosco:

The same white paper boat from the reference drifts along a sunlit forest stream at golden hour, leaves floating beside it, camera tracks low alongside it with the same smooth motion as the reference video. Cinematic, shallow depth of field.

Genera con questo prompt →

Con un video di riferimento, audio deve essere false, non si possono attivare i multi-shot intelligenti e le immagini di riferimento sono al massimo 4. Richiesta minima:

{
  "model": "kling-3.0-omni/reference-to-video",
  "input": {
    "prompt": "The same white paper boat from the reference drifts along a forest stream",
    "image_urls": ["https://static.hiapi.ai/admin-assets/2026/10/13/1791861888668-6554d6167af93003-kling-omni-boat-frame.jpg"],
    "video_urls": ["https://static.hiapi.ai/admin-assets/2026/10/13/1791861859228-2b40d774dd4b2262-kling-omni-t2v-golden.mp4"],
    "duration": 3,
    "resolution": "720p",
    "audio": false
  }
}

Per bloccare più soggetti, usa elements per dare un nome a ciascun soggetto e scrivi @nome nel prompt; per la sintassi completa vedi Esempi di prompt per reference-to-video.

Video transformation: passa 1 video originale in video_urls (MP4/MOV, 3–15.5 secondi, massimo 200MB) e scrivi nel prompt in cosa trasformarlo. La durata e il formato di output seguono il video originale e non viene generato audio. Richiesta minima:

{
  "model": "kling-3.0-omni/transformation",
  "input": {
    "prompt": "Transform the scene into a snowy winter night, keep the exact camera motion",
    "video_urls": ["https://static.hiapi.ai/admin-assets/2026/10/13/1791861859228-2b40d774dd4b2262-kling-omni-t2v-golden.mp4"],
    "resolution": "720p"
  }
}

Lo stesso video della barchetta di carta nella notte di pioggia, trasformato in una barchetta di carta luminosa in una notte di neve:

Transform the scene into a snowy winter night: the gutter becomes a frozen stream with drifting snowflakes, the paper boat becomes a small glowing paper lantern boat, keep the exact camera motion and water movement from the original video. Cinematic, cold blue tones.

Genera con questo prompt →

Quanto costa?

Endpoint	720p	1080p	4K
Text-to / image-to-video, audio disattivato	$0.10/s	$0.129/s	$0.479/s
Text-to / image-to-video, audio attivato	$0.129/s	$0.1645/s	$0.479/s
Reference-to-video, senza video di riferimento	Come sopra	Come sopra	Come sopra
Reference-to-video, con video di riferimento	$0.143/s	$0.193/s	$0.479/s
Video transformation	$0.143/s	$0.193/s	$0.479/s

Un video text-to-video da 5 secondi a 720p con audio disattivato costa $0.50, con $10 si possono generare 100 secondi; il minimo di 3 secondi costa solo $0.30. Per mettere a punto il prompt, usa prima 720p e 3–5 secondi, poi passa a 1080p o 4K una volta definito. I task falliti vengono rimborsati automaticamente.

Note prima del go-live

• Usa il callback invece del polling: aggiungi al livello superiore della richiesta "callback": {"url": "https://tuo-dominio/hiapi/callback"}; HiAPI notificherà attivamente al successo o al fallimento del task, deduplicando per taskId.
• I video vengono conservati per circa 7 giorni: dopo aver ottenuto output[0].url, salvalo altrove; per una conservazione a lungo termine puoi usare lo storage persistente di HiAPI (fatturato separatamente in base allo spazio occupato).
• Scrivi tutti i parametri in base all'endpoint: per text-to-video, image-to-video e reference-to-video specifica esplicitamente resolution, duration, audio; per video transformation scrivi solo resolution, la durata segue il video originale.
• Nomi degli elementi senza spazi: in elements[].name scrivi serum, e nel prompt scrivi @serum.

Domande frequenti

I quattro endpoint vanno attivati separatamente?

No. Basta la stessa API Key, cambiando model.

Si può ottenere un formato verticale?

Sì. Per text-to-video e reference-to-video scrivi 9:16 in aspect_ratio; image-to-video segue le proporzioni del frame iniziale, video transformation segue il video originale.

Come si aggiunge l'audio?

Per text-to-video, image-to-video e reference-to-video (senza video di riferimento) imposta audio su true per generare suoni ambientali ed effetti sonori sincronizzati con l'immagine. A 720p costa $0.029 in più al secondo, a 1080p $0.0355 in più al secondo.

Si possono scrivere prompt in cinese?

Sì. Per risultati più stabili, scrivi in frasi separate come si muove la camera, cosa fa il soggetto, l'illuminazione e lo stile.

Copia il prompt della barchetta di carta nella notte di pioggia qui sopra e vai alla pagina del modello per generare il primo video; per altri esempi copiabili vedi Esempi di prompt per Kling 3.0 Omni, per i dettagli sui prezzi vedi Prezzi dell'API di Kling 3.0.