how-tos

Kling Image 4.0 API-gids: je eerste request in cURL en Python

Poyo.ai Team
9 min read
Share:

Kling Image 4.0 API-gids: je eerste request in cURL en Python

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 files is het framenummer van je storyboard of slideset.

Validatieregels om te controleren voordat je indient

RegelModel
prompt 1–50,000 tekens, niet alleen witruimtebeide
image_urls 1–10 items; elk 30 MB, ≥300 px, verhouding 0.4–2.5kling-4.0-image
kling_elements ≤ 7, elk 2–4 URL's, alleen met image_urls; afbeeldingen + elementen ≤ 10kling-4.0-image
n 1–9 zonder set, 2–10 met enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" vereist 1–3 image_urls; resolution 1K / 2Kkling-4.0-long-image
Geen extra velden (output_format, seed, negative_prompt worden geweigerd)beide

Fouten die je moet afhandelen

codeBetekenisWat te doen
400Ongeldige parametersCorrigeer de body; probeer niet ongewijzigd opnieuw
401Ontbrekende of ongeldige API-sleutelControleer de header
402Onvoldoende creditsVul aan en dien opnieuw in
429Rate limitWacht en probeer het later opnieuw
500 / 502 / 503Server- of upstreamfoutDien 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:

RequestCreditsUSD
Eerste cURL-aanroep hierboven (2K, één afbeelding)13$0.065
Dezelfde prompt in 8K32$0.16
Element-bewerking hierboven (2K, 1 afbeelding + 1 element)15$0.075
Set van vier afbeeldingen in 2K52$0.26
Webpagina in 1K, zonder referenties110$0.55
Medium e-commercepagina in 1K, 1 productfoto95$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."

Share: