API Kling AI da immagine a video in Python

Usa l'API Kling AI da immagine a video in Python tramite l'endpoint per attività asincrone di HiAPI. L'avvio rapido seguente usa l'ID modello attualmente richiamabile kling-3.0-omni/image-to-video, esegue il polling dell'attività fino allo stato terminale e scarica l'MP4 generato.

Per verificare i campi esatti, apri la documentazione dell'API Kling 3.0 Omni da immagine a video. Usa la pagina del modello Omni attuale per vedere il modello e il Playground, e verifica il prezzo Kling API in tempo reale prima di eseguire in produzione.

Avvio rapido: eseguire Kling da immagine a video in Python

Installa requests con python -m pip install requests, imposta HIAPI_API_KEY nell'ambiente e sostituisci IMAGE_URL con un URL JPEG, PNG o WebP pubblico. Lo script completo è il primo blocco di codice copiabile:

import os
import time
from pathlib import Path

import requests

API_BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
IMAGE_URL = "https://cdn.example.com/first-frame.jpg"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "kling-3.0-omni/image-to-video",
    "input": {
        "image_urls": [IMAGE_URL],
        "prompt": "The camera slowly pushes in as leaves move in a light breeze",
        "duration": 5,
        "resolution": "1080p",
        "sound": False,
    },
}

created = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]

deadline = time.time() + 900
while time.time() < deadline:
    response = requests.get(
        f"{API_BASE}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "success":
        output_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(task.get("error") or f"Task {task_id} failed")

    time.sleep(8)
else:
    raise TimeoutError(f"Task {task_id} did not finish within 15 minutes")

with requests.get(output_url, stream=True, timeout=180) as download:
    download.raise_for_status()
    with Path("kling-output.mp4").open("wb") as video:
        for chunk in download.iter_content(1024 * 1024):
            if chunk:
                video.write(chunk)

print("Saved kling-output.mp4")

La richiesta di creazione restituisce un taskId e non attende il completamento della generazione video. Lo script esegue il polling di GET /v1/tasks/{taskId}, si ferma su success o fail e scarica il prima possibile il primo output, poiché l'URL del risultato scade.

Apri il modello Kling Omni e prova questo payload.

Scegliere il modello Kling da immagine a video attualmente disponibile

ID modello	Scenario d'uso	Convenzioni di input e output
kling-3.0-omni/image-to-video	Necessità di controllo del primo/ultimo fotogramma, audio nativo opzionale o 4K	Da uno a due URL di immagini pubblici; 3-15 secondi; 720p, 1080p o 4K
kling-3.0-turbo/image-to-video	Serve solo un fotogramma iniziale e uno schema più semplice a 720p/1080p è sufficiente	Esattamente un URL di immagine pubblico; prompt obbligatorio; 3-15 secondi; 720p o 1080p

Per il riferimento completo dei campi di Omni, vedi la documentazione Omni I2V. Turbo ha un proprio riferimento allo schema Turbo I2V. Entrambi usano lo stesso flusso di creazione e polling su /v1/tasks, quindi puoi mantenere un unico esecutore e sostituire solo model e input.

Corpo della richiesta conforme ai requisiti del modello

Omni con primo e ultimo fotogramma

Invia un URL per il primo fotogramma, oppure due URL nell'ordine [first, last]:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "image_urls": [
      "https://cdn.example.com/first-frame.jpg",
      "https://cdn.example.com/last-frame.jpg"
    ],
    "prompt": "The camera arcs around the subject as the light changes from dawn to noon",
    "duration": 8,
    "resolution": "1080p",
    "sound": true
  }
}

Omni accetta uno o due image_urls. Il suo prompt è opzionale, duration è un intero da 3 a 15, resolution è 720p, 1080p o 4K, e sound è opzionale.

Turbo con un fotogramma iniziale

{
  "model": "kling-3.0-turbo/image-to-video",
  "input": {
    "prompt": "The subject turns toward the camera while leaves move in a light breeze",
    "image_urls": ["https://cdn.example.com/first-frame.jpg"],
    "duration": 8,
    "resolution": "1080p"
  }
}

Turbo richiede un prompt e esattamente una voce in image_urls. Non inviare campi supportati solo da Omni (ad esempio sound) né aggiungere campi da testo a video (ad esempio aspect_ratio); il contenuto visivo è determinato dall'immagine di origine.

Prezzi Kling AI: usa le tariffe in tempo reale, non copiare i prezzi

I prezzi Kling AI su HiAPI sono a consumo. Entrambi i modelli da immagine a video attuali fatturano in base ai secondi generati, con tariffa determinata dal modello e dalla risoluzione; Omni ha anche fasce diverse quando l'audio è abilitato. Clip più lunghe, risoluzioni più alte o audio nativo modificano il costo dell'attività.

Le tariffe possono cambiare, quindi questa guida non fissa una tabella di prezzi in dollari. Prima di pianificare un budget o inviare lotti consistenti di attività, consulta subito la tabella dei prezzi dei modelli in tempo reale.

Kling AI è gratuito?

No: su HiAPI, la generazione tramite l'API Kling da immagine a video non è un'API gratuita illimitata. Le attività andate a buon fine consumano il saldo alle tariffe in tempo reale del modello, della durata, della risoluzione e delle impostazioni audio scelti. Le promozioni dell'account o i bonus per nuovi utenti possono cambiare e possono essere soggetti a condizioni, quindi non considerarli un livello gratuito Kling garantito; prima di inviare un'attività, verifica nell'account le offerte correnti e il tuo saldo.

Controlli di produzione che prevengono attività fallite o duplicate

1. Usa URL di immagini HTTPS scaricabili direttamente. localhost, pagine che richiedono l'accesso, pagine di condivisione HTML e URL firmati scaduti possono fallire dopo la creazione dell'attività.
2. Salva taskId prima di riprovare il worker. Un nuovo tentativo di chiamata di creazione può creare e fatturare una seconda attività.
3. Considera success e fail come stati terminali. In produzione, usa callback.url di primo livello e mantieni il polling come riserva di riconciliazione.
4. Scarica tempestivamente output[].url e copia i risultati da conservare a lungo termine in uno storage che controlli.
5. Convalida lo schema del modello scelto prima dell'invio. Le convenzioni rigorose dei modelli rifiutano i campi sconosciuti.

Errori comuni

• HTTP 400: la richiesta non corrisponde allo schema; controlla i campi indicati, i valori di enumerazione, la lunghezza degli array e i tipi JSON.
• HTTP 401: la chiave bearer manca, non è valida o non può usare il modello scelto.
• L'attività passa a fail: la richiesta di creazione ha superato la convalida, ma il renderer non è riuscito a recuperare l'input o a completare la generazione. Registra separatamente il taskId e l'errore restituito rispetto alla risposta di creazione.
• URL di output scaduto: il rendering può essere riuscito, ma l'URL temporaneo di prelievo non è stato scaricato in tempo.

Domande frequenti

Quale modello Kling da immagine a video dovrei usare in Python?

Usa kling-3.0-omni/image-to-video quando ti servono controllo di uno o due fotogrammi, audio nativo opzionale o 4K. Usa kling-3.0-turbo/image-to-video quando un fotogramma iniziale e un output a 720p/1080p sono sufficienti. Il codice Python di creazione, polling e download resta invariato.

Quali sono gli ID attuali dei modelli Kling AI da immagine a video?

Gli ID attualmente richiamabili trattati in questo articolo sono kling-3.0-omni/image-to-video e kling-3.0-turbo/image-to-video. Invia uno dei due ID nel campo model di primo livello di POST /v1/tasks.

Quante immagini può accettare Kling da immagine a video?

Omni accetta un'immagine come primo fotogramma, oppure due immagini nell'ordine [first, last]. Turbo accetta esattamente un'immagine di fotogramma iniziale.

Quanto costa l'API Kling AI?

Si fattura in base ai secondi generati. La tariffa esatta in tempo reale dipende dal modello e dalla risoluzione, e per Omni anche dalle impostazioni audio. Usa la pagina dei prezzi in tempo reale, non copiare i prezzi statici di questa guida.

Kling AI è gratuito tramite l'API?

Non è garantito un livello gratuito illimitato per l'API Kling. La generazione consuma il saldo dell'account alle tariffe in tempo reale delle attività. Controlla nell'account eventuali offerte starter correnti soggette a condizioni, invece di presumere una quota gratuita fissa.

Perché l'attività fallisce anche se la richiesta di creazione è riuscita?

Il JSON ha superato la convalida iniziale, ma il renderer potrebbe non riuscire a recuperare l'immagine o a completare la generazione. Verifica che l'immagine sia pubblica e non scaduta, poi controlla l'errore dello stato terminale usando il taskId salvato.

Come si ottiene il video generato?

Leggi data.taskId dalla risposta di creazione. Uno script locale può eseguire il polling di GET /v1/tasks/{taskId}, mentre in produzione puoi usare callback.url. In caso di success, scaricalo prima che data.output[0].url scada.

Successivamente leggi il riferimento completo dell'API Kling Omni, poi, quando sei pronto a testare una richiesta, apri la pagina del modello attuale.