how-tos

Guida alla Kling Image 4.0 API: prima richiesta con cURL e Python

Poyo.ai Team
9 min read
Share:

Guida alla Kling Image 4.0 API: prima richiesta con cURL e Python

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

RegolaModello
prompt di 1–50,000 caratteri, non solo spazientrambi
image_urls 1–10 voci; 30 MB, ≥300 px, rapporto 0.4–2.5 ciascunakling-4.0-image
kling_elements ≤ 7, ognuno con 2–4 URL, solo con image_urls; immagini + elementi ≤ 10kling-4.0-image
n 1–9 senza serie, 2–10 con enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" richiede 1–3 image_urls; resolution 1K / 2Kkling-4.0-long-image
Nessun campo extra (output_format, seed, negative_prompt vengono rifiutati)entrambi

Errori da gestire

codeSignificatoCosa fare
400Parametri non validiCorreggi il body; non ritentare senza modifiche
401Chiave API mancante o non validaControlla l'header
402Crediti insufficientiRicarica, poi reinvia
429Rate limitRallenta e riprova più tardi
500 / 502 / 503Errore del server o del fornitore a monteRitenta 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:

RichiestaCreditiUSD
Prima chiamata cURL qui sopra (2K, un'immagine)13$0.065
Stesso prompt in 8K32$0.16
Modifica con elemento qui sopra (2K, 1 immagine + 1 elemento)15$0.075
Serie 2K di quattro immagini52$0.26
Pagina web 1K, senza riferimenti110$0.55
Pagina ecommerce medium 1K, 1 foto prodotto95$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."

Share: