Kuaishou

Kling 4.0

kling-4.0/image-to-video

Modello di generazione video di Kuaishou, in grado di generare in una singola esecuzione video di 30 secondi con audio stereo, supporta il controllo multi-keyframe e di primo/ultimo fotogramma, ideale per brevi video marketing e previsualizzazione di storyboard

kling-4.0/image-to-video kling-4.0/text-to-video

Prova kling-4.0/image-to-video

Input

Output

Compila i parametri e genera: i risultati appariranno qui.

Prezzi

kling-4.0/image-to-video per second

Specifiche	Prezzo unitario
1080P	$0.330

Panoramica

La linea image-to-video di Kling 4.0 è pensata per gli sviluppatori che devono generare un video continuo a partire da una singola immagine del primo fotogramma. Basta fornire un'immagine jpeg o png e una descrizione di movimento, inquadratura ed emozione per ottenere un clip da 3 a 30 secondi, con supporto alle risoluzioni 720p e 1080p e ai formati 16:9, 9:16, 1:1 e 21:9, con tariffazione in base ai secondi di output. È adatta a storyboard pubblicitari, short video per i social e previsualizzazioni narrative, cioè a quei flussi creativi che partono da un'immagine fissa e richiedono il controllo della direzione della camera.

Punti salienti

Il primo fotogramma fissa il punto di partenza: un'immagine funge da punto di partenza dell'inquadratura e, insieme al prompt, guida movimento e direzione della camera, riducendo la deriva dell'immagine tipica della generazione da solo testo.
Durata e formato regolabili in base alla scena: la durata copre da 3 a 30 secondi e il formato può essere orizzontale, verticale, quadrato o widescreen; se non specificato, segue le proporzioni dell'immagine sorgente.
Risoluzione a livelli per bozza e versione finale: 720p per le prove rapide, 1080p per output di livello consegnabile; quest'ultima richiede tempi di rendering sensibilmente più lunghi ed è possibile passare da una all'altra in base alla fase.

Funzionalità

Generazione video guidata dal primo fotogramma: basta un'immagine e un prompt per generare un video; il prompt descrive movimento, inquadratura e atmosfera e il modello prosegue l'inquadratura prendendo il primo fotogramma come riferimento visivo.

Controllo della durata da 3 a 30 secondi: è possibile specificare la lunghezza del clip tramite il parametro di durata; i clip brevi servono per una verifica rapida, quelli lunghi riducono le operazioni di generazione e montaggio successivi, con tariffazione calcolata sui secondi di output.

Risoluzione e formato selezionabili: sono supportati due livelli di output, 720p e 1080p, e i formati 16:9, 9:16, 1:1 e 21:9; se non specificato si mantiene il rapporto dell'immagine sorgente, così da adattarsi rapidamente a diverse posizioni di pubblicazione.

Prompt per la direzione del suono: il campo del prompt può descrivere contemporaneamente anche il suono desiderato, esprimendo in un'unica chiamata sia il movimento visivo sia l'orientamento sonoro.

Casi d'uso

Storyboard pubblicitari: estendere l'inquadratura partendo da un fotogramma fisso del prodotto: basta inserire l'immagine del prodotto e una descrizione del movimento di camera per ottenere clip animate da pochi secondi a decine di secondi, da usare come materiale pubblicitario o come previsualizzazione dello storyboard.
Short video per i social: trasformare un'immagine verticale in movimento: con il formato 9:16 si genera un clip breve a partire da una singola composizione, da pubblicare direttamente nei contenuti verticali.
Previsualizzazione narrativa: far avanzare la trama tramite immagini chiave: dal primo fotogramma della scena, insieme a descrizioni di movimento ed emozione, si generano segmenti utili a verificare a basso costo ritmo dell'inquadratura e continuità narrativa.
Inquadrature d'atmosfera in widescreen: con il formato 21:9 si genera da un'immagine statica un piano sequenza d'atmosfera, da usare per sigle, transizioni o sfondi.

Limiti e consigli di scelta

È supportato solo l'input con una singola immagine del primo fotogramma; non sono disponibili più materiali di riferimento, sequenze di fotogrammi chiave né controllo del primo e dell'ultimo fotogramma. La durata massima per singola generazione è di 30 secondi e la risoluzione è limitata a 720p e 1080p. Il rendering a 1080p richiede tempi sensibilmente più lunghi: prima della consegna finale si consiglia di verificare inquadratura e direzione del movimento a 720p. Se serve generare video da zero a partire dal testo, occorre scegliere la linea text-to-video della stessa serie; per narrazioni lunghe con raccordi precisi tra più inquadrature, è necessario generare i segmenti separatamente e montarli in seguito.

Domande frequenti

Vedi tutte le domande →

Quali sono i requisiti per l'immagine del primo fotogramma?

Un URL accessibile pubblicamente di un'immagine jpeg o png, inserito nell'array image_urls, una sola immagine alla volta. L'immagine verrà utilizzata come fotogramma iniziale del clip.
Cosa succede se non si seleziona il formato?

Se non viene passato aspect_ratio, l'output segue automaticamente le proporzioni del primo fotogramma, quindi un'immagine verticale non viene forzatamente ritagliata in orizzontale. È necessario impostarlo esplicitamente solo quando si desidera sovrascrivere le proporzioni dell'immagine originale.
Il Prompt è obbligatorio?

Sì. L'immagine del primo fotogramma definisce la composizione e il soggetto, mentre il Prompt descrive l'azione, la telecamera e l'audio: sono necessari entrambi. In genere un testo più breve dà risultati migliori.
Come viene fatturata la generazione di video da immagini?

Come per la generazione di video da testo, la fatturazione avviene in base ai secondi di output; le fasce 720p e 1080p hanno prezzi diversi e non è previsto un prezzo minimo.

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-4.0/image-to-video

routestringOpzionale

Valore fisso attuale: default

inputobjectObbligatorio

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

promptstringObbligatoriominLength 1maxLength 2500

Direction for motion, camera and mood. Required: describe what should move and how, and put the sound you want here too.

durationintegerOpzionalePredefinito: 5min 3max 30

Clip length in seconds (3-30). Billed per second.

image_urlsarrayObbligatoriominItems 1maxItems 1

Image the shot starts from. jpeg or png.

Array [ string ]

resolutionstringOpzionalePredefinito: "720p"

Output resolution. 1080p takes noticeably longer to render than 720p.

Opzioni:720p1080p

aspect_ratiostringOpzionale

Frame shape of the output. Leave empty to follow the source image.

Opzioni:16:99:161:121:9

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-4.0/image-to-video",
  "input": {
    "prompt": "…",
    "duration": 5,
    "image_urls": "…",
    "resolution": "720p"
  }
}'

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-4.0/image-to-video",
    input: {
      "prompt": "…",
      "duration": 5,
      "image_urls": "…",
      "resolution": "720p"
    }
  }),
});
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-4.0/image-to-video",
        "input": {
          "prompt": "…",
          "duration": 5,
          "image_urls": "…",
          "resolution": "720p"
        }
    },
)
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"
    }
  }
}