
Deze Kling Image 4.0 API-gids brengt je van een API-sleutel naar een kant-en-klare afbeelding: één cURL-aanroep, een begrensde polling-loop in Python en daarna een werkende JSON-body voor elke invoermodus van kling-4.0-image en kling-4.0-long-image. Probeer ze eerst uit in de Kling Image 4.0-playground; elke request-body hieronder volgt de PoYo-docs.
Je eerste Kling Image 4.0 API-request met cURL
Maak een sleutel aan in het PoYo-dashboard en bewaar die op je server als POYO_API_KEY. Dien daarna een text-to-image-taak in 2K in:
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"
}
}'
De response bevat code: 200 en data.task_id, met status: "not_started". Een ingediende taak is nog geen afgeronde afbeelding. Controleer de taak met:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
De statussen zijn not_started, running, finished en failed. Bij finished bevat data.files één item per afbeelding met file_url en file_type: "image", en data.credits_amount toont wat de taak heeft gekost. Bij failed lees je data.error_message.
Een begrensde polling-loop in Python
Dit draait op je backend met requests. Het controleert zowel de HTTP-status als het code-veld in de body (validatiefouten kunnen binnenkomen als HTTP 200 met code: 400), stopt bij failed en stopt na 20 minuten met wachten zonder opnieuw in te dienen, want een tweede submit is een tweede rekening.
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)
Voeg voor lange jobs in plaats daarvan een "callback_url": "https://your-domain.com/poyo-hook" op het hoogste niveau aan de payload toe. PoYo POST dan dezelfde taakgegevens (zonder de code/data-wrapper) zodra de taak klaar of mislukt is, ondertekend met HMAC-SHA256 in X-Webhook-Signature; de webhook-docs laten zien hoe je die verifieert.
Image-to-image met image_urls
Geef 1 tot 10 publieke HTTP(S)-URL's mee in image_urls. De eerste is @Image1, de tweede @Image2, in de volgorde van de array. Geef elke afbeelding een rol in de prompt en zeg wat ongewijzigd moet blijven.
{
"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 moet een array zijn, ook bij één afbeelding. Elke afbeelding mag maximaal 30 MB zijn, moet minimaal 300 px breed en hoog zijn en een breedte/hoogte-verhouding tussen 0.4 en 2.5 hebben.
Consistente onderwerpen met kling_elements
Een element is één personage of object, getoond vanuit 2 tot 4 hoeken, met het vooraanzicht eerst. Elementen vereisen minstens één image_urls-item, en je kunt er tot 7 meegeven; afbeeldingen plus elementen zijn begrensd op 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"
}
}
Deze request kost 13 credits voor de 2K-afbeelding plus 1 voor de referentieafbeelding en 1 voor het element: 15 credits ($0.075).
Beeldsets met enable_sequential
Met enable_sequential: true loopt n van 2 tot 10 (standaard 4) en plant het model de afbeeldingen als één set met dezelfde onderwerpen en stijl, in volgorde teruggegeven. Staat het uit, dan levert n van 1 tot 9 onafhankelijke afbeeldingen op.
{
"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
}
}
In onze test op de lanceringsdag (PoYo-productie-API, 19 november 2026) leverde een 16:9-set in 2K met n: 4 vier afbeeldingen van 2720×1536 op met dezelfde rijder, motor en outfit bij zonsopgang, 's middags, bij zonsondergang en 's nachts. De set kost 52 credits en het duurde ongeveer 4.9 minuten van submit tot resultaat.
Lange webpagina's en e-commercepagina's
Wissel de model-ID naar kling-4.0-long-image en kies een skill. Een webpagina-ontwerp, optioneel volgens een stijlreferentie:
{
"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"
}
}
Een e-commerce-detailpagina op basis van één productfoto:
{
"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"
}
}
Tip: noem de taal van de pagina. In onze test kwam een Engelse webpagina-prompt die niet zei in welke taal de tekst moest zijn, terug met Chinese tekst op de pagina. Met "All text on the page is in English." in de prompt was dat opgelost; daarom eindigen beide bodies hierboven met die regel. Onze webpaginatest in 1K leverde één afbeelding van 1024×4257 op voor 110 credits, in ongeveer 1.7–2.2 minuten.
image_urls en length horen bij ecommerce; style_image_url en subject_image_url horen bij webpage. Meer over paginalengtes en 8K-output in 8K en lange afbeeldingen met de Kling Image 4.0 API.
De resultaten opslaan
Elke files[].file_url verwijst naar een PNG. Kopieer die naar je eigen opslag in plaats van hem vanuit je app te hotlinken. Drie dingen uit onze run op de lanceringsdag om rekening mee te houden:
- Grootte. Eén 16:9-afbeelding in 8K was een PNG van 10880×6144 van ongeveer 128 MB. Stream hem naar schijf in plaats van hem in het geheugen te laden, en verhoog de read-timeout van je client.
- Alfakanaal. De downloads waren RGBA-PNG's, ook bij ondoorzichtige afbeeldingen. Verwacht je pipeline, CDN of printworkflow RGB of JPEG, converteer dan na het downloaden.
- Volgorde. Een beeldset komt in volgorde terug, dus de index in
filesis het framenummer van je storyboard of slideset.
Validatieregels om te controleren voordat je indient
| Regel | Model |
|---|---|
prompt 1–50,000 tekens, niet alleen witruimte | beide |
image_urls 1–10 items; elk 30 MB, ≥300 px, verhouding 0.4–2.5 | kling-4.0-image |
kling_elements ≤ 7, elk 2–4 URL's, alleen met image_urls; afbeeldingen + elementen ≤ 10 | kling-4.0-image |
n 1–9 zonder set, 2–10 met enable_sequential: true | kling-4.0-image |
resolution 2K / 4K / 8K | kling-4.0-image |
skill: "ecommerce" vereist 1–3 image_urls; resolution 1K / 2K | kling-4.0-long-image |
Geen extra velden (output_format, seed, negative_prompt worden geweigerd) | beide |
Fouten die je moet afhandelen
code | Betekenis | Wat te doen |
|---|---|---|
| 400 | Ongeldige parameters | Corrigeer de body; probeer niet ongewijzigd opnieuw |
| 401 | Ontbrekende of ongeldige API-sleutel | Controleer de header |
| 402 | Onvoldoende credits | Vul aan en dien opnieuw in |
| 429 | Rate limit | Wacht en probeer het later opnieuw |
| 500 / 502 / 503 | Server- of upstreamfout | Dien opnieuw in met backoff |
Een failed taak wordt niet in rekening gebracht, dus opnieuw indienen na een mislukking is veilig. Opnieuw indienen na een timeout aan jouw kant is dat niet: poll eerst dezelfde task_id.
Hoe je eerste rekening wordt berekend
kling-4.0-image kost de prijs per afbeelding maal het aantal afbeeldingen, plus 1 credit voor elk image_urls-item en elk element, eenmaal per request. Bij 1 credit = $0.005:
| Request | Credits | USD |
|---|---|---|
| Eerste cURL-aanroep hierboven (2K, één afbeelding) | 13 | $0.065 |
| Dezelfde prompt in 8K | 32 | $0.16 |
| Element-bewerking hierboven (2K, 1 afbeelding + 1 element) | 15 | $0.075 |
| Set van vier afbeeldingen in 2K | 52 | $0.26 |
| Webpagina in 1K, zonder referenties | 110 | $0.55 |
| Medium e-commercepagina in 1K, 1 productfoto | 95 | $0.475 |
Volledige tabellen en meer voorbeelden staan in Kling Image 4.0 API-prijzen. Voor een overzicht van beide model-ID's, zie Wat is Kling Image 4.0.
Veelgestelde vragen
Hoe roep ik de Kling Image 4.0 API aan met Python?
POST de JSON-body met requests naar https://api.poyo.ai/api/generate/submit, lees data.task_id, poll daarna /api/generate/status/{task_id} tot finished en lees files[].file_url. De loop hierboven doet dit met een deadline en foutcontroles.
Wat is de model-ID van de Kling Image 4.0 API?
kling-4.0-image voor text-to-image, bewerkingen en beeldsets, en kling-4.0-long-image voor lange webpagina's en e-commercepagina's. kling-4-0-image is alleen de pagina-slug.
Ondersteunt de Kling Image 4.0 API webhooks?
Ja. Voeg callback_url toe op het hoogste niveau van de request. PoYo stuurt een ondertekende POST zodra de taak klaar of mislukt is.
Kan ik JPEG-output krijgen van de Kling Image 4.0 API? Er bestaat geen veld voor het outputformaat; resultaten zijn PNG. Onze downloads waren RGBA-PNG's, ook bij ondoorzichtige afbeeldingen, dus converteer zelf als je JPEG nodig hebt.
Waarom kwam mijn lange Kling Image 4.0-webpagina terug in een andere taal? Als de prompt de taal van de paginatekst niet noemt, kan het model er zelf een kiezen. Noem de taal, bijvoorbeeld "All text on the page is in English."