how-tos

Kling Image 4.0 API-guide: første request i cURL og Python

Poyo.ai Team
9 min read
Share:

Kling Image 4.0 API-guide: første request i cURL og Python

Denne Kling Image 4.0 API-guide tager dig fra en API-nøgle til et færdigt billede: ét cURL-kald, en afgrænset polling-løkke i Python og derefter en fungerende JSON-body til hver inputtilstand i kling-4.0-image og kling-4.0-long-image. Prøv dem gerne først i Kling Image 4.0-playgrounden; alle request-bodies nedenfor følger PoYo-dokumentationen.

Din første Kling Image 4.0 API-request med cURL

Opret en nøgle i PoYo-dashboardet, og opbevar den på din server som POYO_API_KEY. Send derefter en tekst-til-billede-task i 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"
    }
  }'

Svaret indeholder code: 200 og data.task_id med status: "not_started". En indsendt task er ikke et færdigt billede. Tjek den med:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Statusserne er not_started, running, finished og failed. Ved finished indeholder data.files én post pr. billede med file_url og file_type: "image", og data.credits_amount viser, hvad tasken kostede. Ved failed skal du læse data.error_message.

En afgrænset polling-løkke i Python

Denne kører på din backend med requests. Den tjekker både HTTP-statussen og feltet code i body'en (valideringsfejl kan komme som HTTP 200 med code: 400), stopper ved failed og opgiver at vente efter 20 minutter uden at sende igen, fordi en ny submit er en ny regning.

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)

Til lange jobs kan du i stedet tilføje en "callback_url": "https://your-domain.com/poyo-hook" på øverste niveau i payloaden. PoYo sender de samme taskdata med POST (uden code/data-wrapperen), når tasken er færdig eller fejler, signeret med HMAC-SHA256 i X-Webhook-Signature; webhook-dokumentationen viser, hvordan du verificerer den.

Billede-til-billede med image_urls

Send 1 til 10 offentlige HTTP(S)-URL'er i image_urls. Den første er @Image1, den anden @Image2, i arrayets rækkefølge. Giv hver af dem en rolle i prompten, og skriv, hvad der skal forblive uændret.

{
  "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 skal være et array, også for ét billede. Hvert billede må højst være 30 MB, mindst 300 px i bredde og højde, med et forhold mellem bredde og højde på mellem 0.4 og 2.5.

Ensartede motiver med kling_elements

Et element er én karakter eller ét objekt vist fra 2 til 4 vinkler, frontalvisningen først. Elements kræver mindst én image_urls-post, og du kan sende op til 7 af dem; billeder plus elements er begrænset til 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"
  }
}

Denne request koster 13 kreditter for 2K-billedet plus 1 for referencebilledet og 1 for elementet: 15 kreditter ($0.075).

Billedsæt med enable_sequential

Med enable_sequential: true går n fra 2 til 10 (standard 4), og modellen planlægger billederne som ét sæt med de samme motiver og samme stil, returneret i rækkefølge. Uden det returnerer n fra 1 til 9 uafhængige billeder.

{
  "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
  }
}

I vores test på lanceringsdagen (PoYos produktions-API, 19. november 2026) returnerede et 16:9-sæt i 2K med n: 4 fire 2720×1536-billeder med samme rytter, motorcykel og påklædning ved daggry, middag, solnedgang og nat. Sættet koster 52 kreditter, og det tog ca. 4.9 minutter fra submit til resultat.

Lange websider og e-handelssider

Skift model-ID til kling-4.0-long-image, og vælg en skill. Et webside-design, eventuelt efter en stilreference:

{
  "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"
  }
}

En produktside til e-handel ud fra ét produktfoto:

{
  "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: angiv sidens sprog. I vores test kom en engelsk webside-prompt, der ikke sagde, hvilket sprog teksten skulle være på, tilbage med kinesisk tekst på siden. Tilføjelsen "All text on the page is in English." til prompten løste det, og derfor slutter begge bodies ovenfor med den linje. Vores 1K-webside-test returnerede ét 1024×4257-billede for 110 kreditter på ca. 1.7–2.2 minutter.

image_urls og length hører til ecommerce; style_image_url og subject_image_url hører til webpage. Mere om sidelængder og 8K-output i 8K og lange billeder med Kling Image 4.0 API.

Gem resultaterne

Hver files[].file_url peger på en PNG. Kopiér den til dit eget lager i stedet for at hotlinke den fra din app. Tre ting fra vores kørsel på lanceringsdagen, som du bør planlægge efter:

  • Størrelse. Ét 16:9-billede i 8K var en 10880×6144 PNG på ca. 128 MB. Stream den til disk i stedet for at indlæse den i hukommelsen, og hæv klientens read timeout.
  • Alfakanal. Downloads var RGBA-PNG'er, selv for uigennemsigtige billeder. Hvis din pipeline, dit CDN eller dit printworkflow forventer RGB eller JPEG, så konvertér efter download.
  • Rækkefølge. Et billedsæt returneres i rækkefølge, så indekset i files er billednummeret i dit storyboard eller slidesæt.

Valideringsregler, der er værd at tjekke før submit

RegelModel
prompt 1–50,000 tegn, ikke kun whitespacebegge
image_urls 1–10 elementer; 30 MB, ≥300 px, forhold 0.4–2.5 hverkling-4.0-image
kling_elements ≤ 7, hver 2–4 URL'er, kun med image_urls; billeder + elements ≤ 10kling-4.0-image
n 1–9 uden sæt, 2–10 med enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" kræver 1–3 image_urls; resolution 1K / 2Kkling-4.0-long-image
Ingen ekstra felter (output_format, seed, negative_prompt afvises)begge

Fejl, der er værd at håndtere

codeBetydningHvad du skal gøre
400Ugyldige parametreRet body'en; prøv ikke igen uændret
401Manglende eller ugyldig API-nøgleTjek headeren
402Utilstrækkelige kreditterFyld op, og send igen
429Rate limitVent, og prøv igen senere
500 / 502 / 503Server- eller upstream-fejlSend submit igen med backoff

En failed task faktureres ikke, så det er sikkert at sende igen efter en fejl. Det er det ikke efter en timeout på din side: poll først det samme task_id.

Sådan beregnes din første regning

kling-4.0-image koster prisen pr. billede gange antallet af billeder plus 1 kredit for hvert image_urls-element og hvert element, én gang pr. request. Med 1 kredit = $0.005:

RequestKreditterUSD
Første cURL-kald ovenfor (2K, ét billede)13$0.065
Samme prompt i 8K32$0.16
Element-redigeringen ovenfor (2K, 1 billede + 1 element)15$0.075
2K-sæt med fire billeder52$0.26
1K-webside, ingen referencer110$0.55
1K medium e-handelsside, 1 produktfoto95$0.475

Komplette tabeller og flere eksempler findes i Kling Image 4.0 API-priser. For et overblik over begge model-ID'er, se Hvad er Kling Image 4.0.

Ofte stillede spørgsmål

Hvordan kalder jeg Kling Image 4.0 API med Python? Send JSON-body'en med POST til https://api.poyo.ai/api/generate/submit med requests, læs data.task_id, poll derefter /api/generate/status/{task_id}, indtil den er finished, og læs files[].file_url. Løkken ovenfor gør dette med en deadline og fejltjek.

Hvad er model-ID'et for Kling Image 4.0 API? kling-4.0-image til tekst-til-billede, redigeringer og billedsæt, og kling-4.0-long-image til lange websider og e-handelssider. kling-4-0-image er kun sidens slug.

Understøtter Kling Image 4.0 API webhooks? Ja. Tilføj callback_url på øverste niveau i requesten. PoYo sender en signeret POST, når tasken er færdig eller fejler.

Kan jeg få JPEG-output fra Kling Image 4.0 API? Der findes intet felt til outputformat; resultaterne er PNG. Vores downloads var RGBA-PNG'er, selv for uigennemsigtige billeder, så konvertér på din side, hvis du har brug for JPEG.

Hvorfor kom min lange Kling Image 4.0-webside tilbage på et andet sprog? Hvis prompten ikke angiver sproget for sidens tekst, kan modellen vælge et. Angiv det, for eksempel "All text on the page is in English."

Share: