Kuaishou

Kling 3.0

kling-3.0-omni/reference-to-video

Serie unificata di generazione video multimodale, supporta la generazione di video da testo, da immagine, da riferimento e il montaggio all'interno del video, con sincronizzazione labiale nativa e audio multilingue

kling-3.0-omni/image-to-video kling-3.0-omni/reference-to-video kling-3.0-omni/text-to-video kling-3.0-omni/transformation kling-3.0/image-to-video kling-3.0/motion-control kling-3.0/text-to-video

Prova kling-3.0-omni/reference-to-video

Input

Subjects

Creazioni

Vedi tutte le creazioni

Output

video

Compila i parametri e genera: i risultati appariranno qui.

Prezzi

kling-3.0-omni/reference-to-video per second

Specifiche	720P	1080P	4K
Sound Off · Without Reference Videos	$0.100	$0.129	$0.479
Sound On · Without Reference Videos	$0.129	$0.1645	$0.479
Sound Off · With Reference Videos	$0.143	$0.193	$0.479
Sound On · With Reference Videos	$0.143	$0.193	$0.479

Panoramica

kling-3.0-omni/reference-to-video è la linea della serie Kling 3.0 Omni dedicata alla generazione di video a partire da immagini di riferimento: consente di usare da 1 a 7 immagini di riferimento (oppure fino a 7 elementi soggetto riutilizzabili) come ancore visive, insieme a un prompt testuale, per generare video da 3 a 15 secondi. Supporta risoluzioni 720p, 1080p e 4k e formati 16:9, 9:16 e 1:1, con possibilità di attivare audio nativo e multishot intelligente. È ideale per gli sviluppatori che necessitano di mantenere la coerenza di personaggi o oggetti tra inquadrature diverse e di produrre video in batch per marketing e social media.

Punti salienti

Doppio ancoraggio: immagini di riferimento multiple ed elementi soggetto——è possibile inviare da 1 a 7 immagini di riferimento, oppure definire fino a 7 elementi soggetto con 2-4 immagini ciascuno e richiamarli nel prompt tramite @name.
Video di riferimento opzionale in sovrapposizione——è possibile aggiungere 1 video di riferimento da 3 a 15,5 secondi per vincolare movimento e composizione; in questo caso il limite complessivo di immagini di riferimento ed elementi scende a 4.
Risoluzione e formato dal verticale al 4K——output selezionabile tra 720p, 1080p e 4k, con formati 16:9, 9:16 e 1:1, adatti sia alla distribuzione orizzontale sia a quella verticale per i video brevi.
Audio nativo e multishot combinabili——audio nativo (disattivato per impostazione predefinita) e multishot intelligente possono essere attivati contemporaneamente per generare in un'unica passata clip multishot con audio; entrambi non sono disponibili quando si utilizza un video di riferimento.

Descrizione delle capacità

Generazione coerente multi-soggetto: tramite elements si definiscono nome, descrizione e da 2 a 4 immagini dello stesso soggetto, richiamabili nel prompt con @name, in modo che lo stesso personaggio o oggetto mantenga un aspetto coerente in più inquadrature.

Vincolo da video di riferimento: passando 1 video di riferimento MP4/MOV (massimo 200MB, 3-15,5 secondi) si guidano movimento e ritmo, soluzione adatta a generazioni stilizzate o a una sorta di rifacimento a partire da materiale esistente.

Controllo di risoluzione e formato: scegliere l'output a 720p, 1080p o 4k in base al canale di distribuzione e impostare il formato 16:9, 9:16 o 1:1, riducendo ritagli e transcodifiche in post-produzione.

Audio nativo e multishot intelligente: attivando audio si genera il suono in sincrono; attivando prefer_multi_shots il modello suddivide automaticamente in più inquadrature in base al prompt. Entrambi sono disponibili quando non si usa un video di riferimento.

Durata e lunghezza del prompt regolabili: la durata dell'output è impostabile da 3 a 15 secondi in base alle esigenze narrative; il prompt può arrivare a 3072 caratteri, sufficienti a descrivere soggetto, azioni e regia delle inquadrature.

Casi d'uso

Team di marketing del brand: immagini di riferimento + prompt sui punti di forza del prodotto——bloccare l'aspetto con immagini di riferimento multiangolari del prodotto e produrre brevi video con formato e risoluzione specifici, pronti per i feed e il sito web.
Gestione social media: elementi personaggio + script verticale——dopo aver definito elementi personaggio fissi, generare in batch video brevi 9:16 mantenendo la coerenza del personaggio, per la produzione di contenuti quotidiani.
Pre-produzione audiovisiva e animazione: video di riferimento + prompt storyboard——usare un video di riferimento per vincolare il ritmo del movimento e ottenere clip multishot di previsualizzazione, per far confermare al regista il design delle inquadrature e i punti di montaggio.
Team di contenuti e-commerce: da set di immagini prodotto a video——caricare immagini di riferimento del prodotto e impostare il formato 1:1 o 16:9 per generare video dimostrativi da usare nelle pagine di dettaglio e negli slot dell'immagine principale del prodotto.

Limiti e suggerimenti di scelta

Il totale di immagini di riferimento ed elementi soggetto non può superare 7; aggiungendo un video di riferimento il limite scende a 4 e audio nativo e multishot intelligente non sono disponibili. La durata massima per singola generazione è di 15 secondi, quindi le narrazioni lunghe vanno generate a segmenti e poi montate. Le immagini di riferimento devono essere JPG/PNG, non superare 50MB ciascuna e avere il lato più corto di almeno 300px; il video di riferimento deve essere MP4/MOV da 3 a 15,5 secondi. Se serve solo la generazione da una singola immagine o da testo puro, si possono scegliere le linee image-to-video o text-to-video della stessa serie; per esigenze specifiche di controllo del movimento si può valutare motion-control.

Novità

Vedi il changelog →

Nuovo modello Nuovo modello: Kling 3.0 Omni (可灵 O3), richiamabile tramite POST /v1/tasks. kling-3.0-omn… Oct 12, 2026

Domande frequenti

Vedi tutte le domande →

Kling 3.0 Image-to-Video richiede il caricamento di un'immagine?

Sì. Attualmente kling-3.0/image-to-video è una pipeline image-to-video: l'immagine di input definisce il soggetto e la composizione iniziale, mentre il Prompt gestisce i movimenti, la telecamera e i cambiamenti dell'ambiente.
Quali durate e risoluzioni supporta Kling 3.0 Image-to-Video?

L'attuale contratto di richiesta di HiAPI supporta 3–15s, con risoluzioni di output 720p, 1080p e 4K. I valori disponibili sono quelli indicati nel pannello dei parametri della pagina e nella documentazione API.
Come viene fatturato Kling 3.0 Image-to-Video?

Le attività vengono fatturate in base alla durata dell'output e al livello selezionato. La pagina mostra il prezzo in tempo reale seguendo l'unità monetaria globale; l'addebito finale fa riferimento al record delle attività completate con successo.
Come migliorare la stabilità del soggetto nella generazione di video da immagine?

Usa un'immagine di input con un soggetto chiaro, poche occlusioni e una composizione completa; nel Prompt descrivi prima l'azione principale e la ripresa, poi elenca gli aspetti dell'aspetto, i materiali e le relazioni con lo sfondo che devono essere preservati. Per il primo test si consiglia una durata breve.

Crea un'attività di generazione

POST https://api.hiapi.ai/v1/tasks

Header

AuthorizationstringObbligatorio

Chiave API dell'account. Obbligatoria in ogni richiesta. Esempio: Bearer YOUR_HIAPI_API_KEY. Ottieni una chiave API

Content-TypestringOpzionale

Il corpo della richiesta viene sempre interpretato come JSON; se inviato, è accettato solo application/json (charset facoltativo) — qualsiasi altro valore restituisce 415. Esempio: application/json.

Idempotency-KeystringOpzionale

Chiave di idempotenza, fino a 255 byte. I retry con la stessa chiave dello stesso account creano l'attività una sola volta; i replay restituiscono il taskId originale.

Chiave di idempotenza

In caso di timeout di rete o retry automatici del client, la stessa chiave crea l'attività una sola volta, senza doppi addebiti (ambito = l'account della chiave API). Usa un identificatore univoco di business (es. "order-42"); i replay restituiscono il taskId originale e le chiavi scadono 24 ore dopo la prima richiesta. La matrice completa degli scenari è nell'introduzione dell'API asincrona unificata.

Corpo

modelstringObbligatorio

Valore fisso attuale: kling-3.0-omni/reference-to-video

routestringOpzionale

Valore fisso attuale: default

inputobjectObbligatorio

Oggetto di parametri di business per kling-3.0-omni/reference-to-video e la route default — vedi la tabella dei parametri sotto.

audiobooleanOpzionalePredefinito: false

Indica se generare contemporaneamente all'video un audio nativo sincronizzato con le immagini; valore booleano, predefinito false; non disponibile quando viene fornito un video di riferimento (video_urls).

promptstringObbligatoriominLength 1maxLength 3072

Descrive il contenuto del video che si desidera generare; per utilizzare un soggetto presente in elements, è possibile farvi riferimento nel prompt con la forma @name usando il suo nome.

durationintegerOpzionalePredefinito: 5min 3max 15

Durata del video di output, in secondi, numero intero, intervallo 3-15, predefinito 5.

elementsarrayOpzionalemaxItems 7

Elenco di soggetti riutilizzabili, massimo 7; ogni elemento contiene un nome, una breve descrizione e 2-4 immagini, e può essere citato nel prompt con @name.

Array [ object ]

Elementi dell'array

namestringObbligatoriominLength 1

Nome univoco del soggetto, utilizzato per farvi riferimento nel prompt nella forma @name; il nome non può contenere spazi.

descriptionstringObbligatoriominLength 1

Breve testo descrittivo del soggetto, utile al modello per riconoscerlo e riprodurlo.

element_input_urlsarrayObbligatoriominItems 2maxItems 4

Array di immagini di riferimento dello stesso soggetto; è necessario fornirne 2-4, in formato JPG/PNG.

Array [ string ]

image_urlsarrayObbligatoriominItems 1maxItems 7

Array di immagini di riferimento, da 1 a 7; se viene aggiunto un video di riferimento, massimo 4, e il totale di immagini di riferimento e soggetti (elements) non deve superare 7 (con un video di riferimento, il totale non deve superare 4). Supporta JPG/PNG, massimo 50MB per immagine, lato minimo 300 px.

Array [ string ]

resolutionstringOpzionalePredefinito: "720p"

Risoluzione del video di output, stringa, predefinita 720p.

Opzioni:720p1080p4k

video_urlsarrayOpzionaleminItems 1maxItems 1

Array opzionale di video di riferimento, supporta MP4 o MOV, massimo 200MB per file, durata 3-15,5 secondi, larghezza e altezza 700-4553 px, frame rate 24-60 fps; dopo l'aggiunta di un video di riferimento non sono supportati audio nativo e multi-inquadratura intelligente.

Array [ string ]

aspect_ratiostringOpzionalePredefinito: "16:9"

Proporzioni del video di output, stringa, predefinite 16:9.

Opzioni:16:99:161:1

prefer_multi_shotsbooleanOpzionalePredefinito: false

Indica se lasciare che il modello pianifichi automaticamente più inquadrature in base al prompt; valore booleano, predefinito false; non disponibile dopo l'aggiunta di un video di riferimento.

callbackobjectOpzionale

Configurazione di notifica dello stato terminale. Se omessa, nessun callback: interroga l'attività per conto tuo.

Callback (Webhook)

Fornisci callback.url in creazione e HiAPI invierà un POST al tuo servizio allo stato terminale, senza polling. Il corpo del callback replica la struttura del dettaglio attività; verifica firma, retry e idempotenza sono descritti nell'introduzione dell'API asincrona unificata.

urlstringObbligatorio

Obbligatoria se è presente callback. Allo stato terminale viene inviato un POST a questo URL; deve essere un URL http(s) valido.

whenstringOpzionalePredefinito: "final"

Al momento è supportato solo final: notifica sia su success sia su fail.

Opzioni:final

storagestringOpzionalePredefinito: "temp"

Livello di archiviazione degli artefatti: temp (predefinito, ~7 giorni) o persistent (a lungo termine, fatturato per dimensione). Saldo insufficiente o superamento del limite ⇒ declassamento silenzioso a temp; il livello effettivo è visibile nella risposta di dettaglio.

Opzioni:temppersistent

Esempi di richiesta

# Invia un'attività asincrona; restituisce subito un taskId (senza attendere la generazione)
curl -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/reference-to-video",
  "input": {
    "audio": false,
    "prompt": "…",
    "duration": 5,
    "image_urls": "…",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "prefer_multi_shots": false
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "kling-3.0-omni/reference-to-video",
    input: {
      "audio": false,
      "prompt": "…",
      "duration": 5,
      "image_urls": "…",
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "prefer_multi_shots": false
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "kling-3.0-omni/reference-to-video",
        "input": {
          "audio": False,
          "prompt": "…",
          "duration": 5,
          "image_urls": "…",
          "resolution": "720p",
          "aspect_ratio": "16:9",
          "prefer_multi_shots": False
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Ottieni i dettagli dell'attività

GET https://api.hiapi.ai/v1/tasks/:id

Campi della risposta

taskIdstringObbligatorio

ID attività, sempre con prefisso tk-hiapi-.

modelstringObbligatorio

Nome completo risolto del modello. Le attività inviate con il parametro route restituiscono base@route (es. gpt-image-2/text-to-image@ext); altrimenti coincide con il nome inviato.

routestringOpzionale

Presente solo se è stato usato il parametro route esplicito; restituisce il valore inviato.

statusstringObbligatorio

Stato dell'attività.

Valori di stato

queued In coda, non avviata. handling In elaborazione. archiving Elaborazione conclusa, preparazione artefatti. success Terminale: completato, artefatti disponibili (restituisce output). fail Terminale: errore (restituisce error). Dopo l'invio, segui status: success e fail sono terminali, il resto no. Esegui polling ogni 1–3 s fino allo stato terminale. In caso di successo scarica gli artefatti da output[].url e trasferiscili prima di expireAt; per conservazione lunga usa storage: "persistent" in creazione.

creatednumberObbligatorio

Istante di creazione dell'attività (secondi Unix).

completednumberObbligatorio

Secondi Unix dello stato terminale; 0 finché non terminale.

outputarrayOpzionale

Presente solo con status == success. Elenco artefatti — sempre un array; un'attività può restituire più type contemporaneamente (es. video + first_frame).

Array [ object ]

Elementi dell'array

urlstringObbligatorio

URL dell'artefatto, scaricabile direttamente.

typestringObbligatorio

Valori attualmente possibili: video, image, audio, first_frame, last_frame, thumbnail; potrebbero essere ampliati in futuro.

expireAtnumberObbligatorio

Secondi Unix di disponibilità dell'artefatto; scarica o trasferisci prima della scadenza.

errorobjectOpzionale

Presente solo con status == fail.

codestringObbligatorio

Codice errore di business.

messagestringObbligatorio

Descrizione dell'errore.

Esempi di risposta

Successo

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

In elaborazione (non terminale)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Non riuscito

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}