
Questa guida alla Kling Image 4.0 API ti porta da una chiave API a un'immagine finita: una chiamata cURL, un ciclo di polling in Python con limite di tempo, poi un body JSON funzionante per ogni modalità di input di kling-4.0-image e kling-4.0-long-image. Prova ciascuno prima nel playground di Kling Image 4.0; ogni body di richiesta qui sotto segue la documentazione PoYo.
La tua prima richiesta alla Kling Image 4.0 API con cURL
Crea una chiave nella dashboard PoYo e conservala sul tuo server come POYO_API_KEY. Poi invia un task text-to-image in 2K:
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-4.0-image",
"input": {
"prompt": "High fashion model wearing a dress made of living moss, standing in an abandoned greenhouse, shafts of light, editorial photography",
"size": "16:9",
"resolution": "2K"
}
}'
La risposta contiene code: 200 e data.task_id, con status: "not_started". Un task inviato non è un'immagine finita. Controllalo con:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Gli stati sono not_started, running, finished e failed. Con finished, data.files contiene una voce per immagine con file_url e file_type: "image", e data.credits_amount mostra quanto è costato il task. Con failed, leggi data.error_message.
Un ciclo di polling in Python con limite
Questo codice gira sul tuo backend con requests. Controlla sia lo stato HTTP sia il campo code nel body (gli errori di validazione possono arrivare come HTTP 200 con code: 400), si ferma su failed e smette di attendere dopo 20 minuti senza reinviare, perché un secondo invio è una seconda fattura.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(resp):
resp.raise_for_status()
body = resp.json()
if body.get("code") != 200:
raise RuntimeError(f"PoYo error {body.get('code')}: {body.get('error')}")
return body["data"]
def run(payload, max_wait=1200, every=10):
task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
return [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
time.sleep(every)
raise TimeoutError("still running, poll task " + task_id + " again later")
urls = run({
"model": "kling-4.0-image",
"input": {
"prompt": "A ceramic pour-over kettle on a walnut counter, morning window light",
"size": "1:1",
"resolution": "2K",
},
})
print(urls)
Per i job lunghi, aggiungi invece al payload un "callback_url": "https://your-domain.com/poyo-hook" al livello superiore. PoYo invia in POST gli stessi dati del task (senza l'involucro code/data) quando il task termina o fallisce, firmati con HMAC-SHA256 in X-Webhook-Signature; la documentazione dei webhook spiega come verificarli.
Image-to-image con image_urls
Passa da 1 a 10 URL HTTP(S) pubblici in image_urls. Il primo è @Image1, il secondo @Image2, nell'ordine dell'array. Assegna a ciascuno un ruolo nel prompt e indica cosa deve restare invariato.
{
"model": "kling-4.0-image",
"input": {
"prompt": "Turn @Image1 into a late-evening scene with warm window light. Keep the furniture, layout and camera angle of @Image1 unchanged.",
"image_urls": ["https://example.com/living-room.png"],
"resolution": "2K"
}
}
image_urls deve essere un array anche per una sola immagine. Ogni immagine deve pesare al massimo 30 MB, misurare almeno 300 px in larghezza e in altezza e avere un rapporto larghezza/altezza tra 0.4 e 2.5.
Soggetti coerenti con kling_elements
Un elemento è un personaggio o un oggetto mostrato da 2 a 4 angolazioni, con la vista frontale per prima. Gli elementi richiedono almeno una voce in image_urls e puoi passarne fino a 7; immagini più elementi hanno un limite di 10.
{
"model": "kling-4.0-image",
"input": {
"prompt": "Place @Element1 sitting on the sofa in @Image1, reading a book in warm evening light. Keep the room layout of @Image1 unchanged.",
"image_urls": ["https://example.com/living-room.png"],
"kling_elements": [
{
"element_input_urls": [
"https://example.com/character-front.png",
"https://example.com/character-side.png",
"https://example.com/character-back.png"
]
}
],
"resolution": "2K"
}
}
Questa richiesta costa 13 crediti per l'immagine 2K più 1 per l'immagine di riferimento e 1 per l'elemento: 15 crediti ($0.075).
Serie di immagini con enable_sequential
Con enable_sequential: true, n va da 2 a 10 (predefinito 4) e il modello pianifica le immagini come un'unica serie con gli stessi soggetti e lo stesso stile, restituite in ordine. Con l'opzione disattivata, n da 1 a 9 restituisce immagini indipendenti.
{
"model": "kling-4.0-image",
"input": {
"prompt": "A four-panel story of a paper boat drifting from a rainy city gutter to a calm sunny lake, same boat in every panel, watercolor style",
"size": "3:2",
"enable_sequential": true,
"n": 4
}
}
Nel nostro test del giorno del lancio (API di produzione PoYo, 19 novembre 2026), una serie 16:9 in 2K con n: 4 ha restituito quattro immagini 2720×1536 con lo stesso motociclista, la stessa moto e lo stesso outfit tra alba, mezzogiorno, tramonto e notte. Costa 52 crediti e sono serviti circa 4.9 minuti dall'invio al risultato.
Pagine web lunghe e pagine ecommerce
Cambia l'ID modello in kling-4.0-long-image e scegli uno skill. Un design di pagina web, opzionalmente basato su un riferimento di stile:
{
"model": "kling-4.0-long-image",
"input": {
"prompt": "Design a long image for a specialty coffee brand's official website, including the hero section, product showcase, roasting philosophy, store information, and footer. Follow the visual style of @StyleImage. All text on the page is in English.",
"skill": "webpage",
"style_image_url": "https://example.com/style-reference.png",
"resolution": "2K"
}
}
Una pagina prodotto ecommerce da una foto prodotto:
{
"model": "kling-4.0-long-image",
"input": {
"prompt": "Design a product detail page for the insulated water bottle in @Image1: hero shot, key features, capacity and size, materials, and lifestyle scenes. All text on the page is in English.",
"skill": "ecommerce",
"image_urls": ["https://example.com/water-bottle.png"],
"length": "medium",
"resolution": "1K"
}
}
Suggerimento: indica la lingua della pagina. Nel nostro test, un prompt webpage in inglese che non specificava la lingua del testo è tornato con testo in cinese sulla pagina. Aggiungere "All text on the page is in English." al prompt ha risolto, ed è per questo che entrambi i body qui sopra terminano con quella riga. Il nostro test webpage in 1K ha restituito un'immagine 1024×4257 per 110 crediti in circa 1.7–2.2 minuti.
image_urls e length appartengono a ecommerce; style_image_url e subject_image_url appartengono a webpage. Maggiori dettagli su lunghezze di pagina e output 8K in 8K e immagini lunghe con la Kling Image 4.0 API.
Salvare i risultati
Ogni files[].file_url punta a un PNG. Copialo nel tuo storage invece di collegarlo direttamente dalla tua app. Tre aspetti emersi dal test del giorno del lancio da pianificare:
- Dimensioni. Un'immagine 16:9 in 8K era un PNG 10880×6144 di circa 128 MB. Scrivilo su disco in streaming invece di caricarlo in memoria, e aumenta il timeout di lettura del client.
- Canale alfa. I download erano PNG RGBA anche per immagini opache. Se la tua pipeline, la CDN o il flusso di stampa si aspetta RGB o JPEG, converti dopo il download.
- Ordine. Una serie di immagini viene restituita in ordine, quindi l'indice in
filesè il numero del frame del tuo storyboard o della tua serie di slide.
Regole di validazione da controllare prima dell'invio
| Regola | Modello |
|---|---|
prompt di 1–50,000 caratteri, non solo spazi | entrambi |
image_urls 1–10 voci; 30 MB, ≥300 px, rapporto 0.4–2.5 ciascuna | kling-4.0-image |
kling_elements ≤ 7, ognuno con 2–4 URL, solo con image_urls; immagini + elementi ≤ 10 | kling-4.0-image |
n 1–9 senza serie, 2–10 con enable_sequential: true | kling-4.0-image |
resolution 2K / 4K / 8K | kling-4.0-image |
skill: "ecommerce" richiede 1–3 image_urls; resolution 1K / 2K | kling-4.0-long-image |
Nessun campo extra (output_format, seed, negative_prompt vengono rifiutati) | entrambi |
Errori da gestire
code | Significato | Cosa fare |
|---|---|---|
| 400 | Parametri non validi | Correggi il body; non ritentare senza modifiche |
| 401 | Chiave API mancante o non valida | Controlla l'header |
| 402 | Crediti insufficienti | Ricarica, poi reinvia |
| 429 | Rate limit | Rallenta e riprova più tardi |
| 500 / 502 / 503 | Errore del server o del fornitore a monte | Ritenta l'invio con backoff |
Un task failed non viene addebitato, quindi reinviare dopo un errore è sicuro. Reinviare dopo un timeout lato tuo no: interroga prima lo stesso task_id.
Come viene calcolata la tua prima fattura
kling-4.0-image costa il prezzo per immagine moltiplicato per il numero di immagini, più 1 credito per ogni voce di image_urls e ogni elemento, una volta per richiesta. Con 1 credito = $0.005:
| Richiesta | Crediti | USD |
|---|---|---|
| Prima chiamata cURL qui sopra (2K, un'immagine) | 13 | $0.065 |
| Stesso prompt in 8K | 32 | $0.16 |
| Modifica con elemento qui sopra (2K, 1 immagine + 1 elemento) | 15 | $0.075 |
| Serie 2K di quattro immagini | 52 | $0.26 |
| Pagina web 1K, senza riferimenti | 110 | $0.55 |
| Pagina ecommerce medium 1K, 1 foto prodotto | 95 | $0.475 |
Tabelle complete e altri esempi sono in prezzi della Kling Image 4.0 API. Per una panoramica di entrambi gli ID modello, vedi cos'è Kling Image 4.0.
Domande frequenti
Come chiamo la Kling Image 4.0 API con Python?
Invia in POST il body JSON a https://api.poyo.ai/api/generate/submit con requests, leggi data.task_id, poi interroga /api/generate/status/{task_id} fino a finished e leggi files[].file_url. Il ciclo qui sopra lo fa con una scadenza e controlli sugli errori.
Qual è l'ID modello della Kling Image 4.0 API?
kling-4.0-image per text-to-image, modifiche e serie di immagini, e kling-4.0-long-image per pagine web lunghe e pagine ecommerce. kling-4-0-image è solo lo slug della pagina.
La Kling Image 4.0 API supporta i webhook?
Sì. Aggiungi callback_url al livello superiore della richiesta. PoYo invia una POST firmata quando il task termina o fallisce.
Posso ottenere output JPEG dalla Kling Image 4.0 API? Non esiste un campo per il formato di output; i risultati sono PNG. I nostri download erano PNG RGBA anche per immagini opache, quindi converti lato tuo se ti serve JPEG.
Perché la mia pagina web lunga di Kling Image 4.0 è tornata in un'altra lingua? Se il prompt non indica la lingua del testo della pagina, il modello può sceglierne una. Specificala, per esempio "All text on the page is in English."