how-tos

Kling Image 4.0 API-guide: første forespørsel med cURL og Python

Poyo.ai Team
9 min read
Share:

Kling Image 4.0 API-guide: første forespørsel med cURL og Python

Denne guiden til Kling Image 4.0 API tar deg fra en API-nøkkel til et ferdig bilde: ett cURL-kall, en Python-pollingløkke med tidsgrense, og deretter en fungerende JSON-body for hver inputmodus i kling-4.0-image og kling-4.0-long-image. Prøv dem gjerne først i Kling Image 4.0-playgrounden; alle forespørselsbodyene nedenfor følger PoYo-dokumentasjonen.

Din første forespørsel til Kling Image 4.0 API med cURL

Opprett en nøkkel i PoYo-dashbordet og oppbevar den på serveren din som POYO_API_KEY. Send deretter inn en 2K tekst-til-bilde-oppgave:

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 har code: 200 og data.task_id, med status: "not_started". En innsendt oppgave er ikke et ferdig bilde. Sjekk den med:

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

Statusene er not_started, running, finished og failed. Ved finished inneholder data.files én oppføring per bilde med file_url og file_type: "image", og data.credits_amount viser hva oppgaven kostet. Ved failed leser du data.error_message.

En Python-pollingløkke med tidsgrense

Denne kjører på backenden din med requests. Den sjekker både HTTP-statusen og feltet code i bodyen (valideringsfeil kan komme som HTTP 200 med code: 400), stopper ved failed, og slutter å vente etter 20 minutter uten å sende inn på nytt, fordi en ny innsending 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)

For lange jobber legger du heller til "callback_url": "https://your-domain.com/poyo-hook" på toppnivå i payloaden. PoYo sender de samme oppgavedataene med POST (uten code/data-innpakningen) når oppgaven er ferdig eller feiler, signert med HMAC-SHA256 i X-Webhook-Signature; webhook-dokumentasjonen viser hvordan du verifiserer den.

Bilde-til-bilde med image_urls

Send 1 til 10 offentlige HTTP(S)-URL-er i image_urls. Den første er @Image1, den andre @Image2, i rekkefølgen i arrayet. Gi hver av dem en rolle i prompten, og si hva som ikke skal endres.

{
  "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 må være et array også for ett enkelt bilde. Hvert bilde kan være maks 30 MB, minst 300 px bredt og høyt, med et forhold mellom bredde og høyde på 0.4 til 2.5.

Konsistente motiver med kling_elements

Et element er én karakter eller ett objekt vist fra 2 til 4 vinkler, med frontvisningen først. Elementer krever minst én oppføring i image_urls, og du kan sende opptil 7 av dem; bilder pluss elementer er begrenset 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 forespørselen koster 13 kreditter for 2K-bildet pluss 1 for referansebildet og 1 for elementet: 15 kreditter ($0.075).

Bildeserier med enable_sequential

Med enable_sequential: true går n fra 2 til 10 (standard 4), og modellen planlegger bildene som én serie med samme motiver og stil, returnert i rekkefølge. Når det er slått av, returnerer n fra 1 til 9 uavhengige bilder.

{
  "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 testen vår på lanseringsdagen (PoYos produksjons-API, 19. november 2026) returnerte en 16:9-serie i 2K med n: 4 fire 2720×1536-bilder med samme rytter, motorsykkel og antrekk ved daggry, midt på dagen, solnedgang og natt. Den koster 52 kreditter og tok omtrent 4.9 minutter fra innsending til resultat.

Lange nettsider og e-handelssider

Bytt modell-ID til kling-4.0-long-image og velg en skill. Et nettsidedesign, eventuelt etter en stilreferanse:

{
  "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 for e-handel fra ett produktbilde:

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

Tips: oppgi språket på siden. I testen vår kom en engelsk nettside-prompt som ikke sa hvilket språk teksten skulle være på, tilbake med kinesisk tekst på siden. Å legge til "All text on the page is in English." i prompten løste det, og derfor slutter begge bodyene ovenfor med den linjen. 1K-nettsidetesten vår returnerte ett 1024×4257-bilde for 110 kreditter på omtrent 1.7–2.2 minutter.

image_urls og length hører til ecommerce; style_image_url og subject_image_url hører til webpage. Mer om sidelengder og 8K-output i 8K og lange bilder med Kling Image 4.0 API.

Lagre resultatene

Hver files[].file_url peker til en PNG. Kopier den til din egen lagring i stedet for å hotlinke den fra appen. Tre ting fra kjøringen på lanseringsdagen som du bør planlegge for:

  • Størrelse. Ett 16:9 8K-bilde var en 10880×6144 PNG på omtrent 128 MB. Strøm den til disk i stedet for å laste den inn i minnet, og øk lese-timeouten i klienten.
  • Alfakanal. Nedlastingene var RGBA-PNG-er selv for ugjennomsiktige bilder. Hvis pipelinen, CDN-et eller trykkarbeidsflyten forventer RGB eller JPEG, konverter etter nedlasting.
  • Rekkefølge. En bildeserie returneres i rekkefølge, så indeksen i files er bildenummeret i storyboardet eller lysbildeserien din.

Valideringsregler du bør sjekke før innsending

RegelModell
prompt 1–50,000 tegn, ikke bare mellomrombegge
image_urls 1–10 elementer; 30 MB, ≥300 px, forhold 0.4–2.5 hverkling-4.0-image
kling_elements ≤ 7, hver med 2–4 URL-er, kun sammen med image_urls; bilder + elementer ≤ 10kling-4.0-image
n 1–9 uten serie, 2–10 med enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" krever 1–3 image_urls; resolution 1K / 2Kkling-4.0-long-image
Ingen ekstra felt (output_format, seed, negative_prompt avvises)begge

Feil som bør håndteres

codeBetydningHva du gjør
400Ugyldige parametereRett bodyen; ikke prøv på nytt uendret
401Manglende eller ugyldig API-nøkkelSjekk headeren
402Ikke nok kreditterFyll på, og send inn på nytt
429Rate limitVent og prøv igjen senere
500 / 502 / 503Server- eller upstream-feilSend inn på nytt med backoff

En failed-oppgave belastes ikke, så det er trygt å sende inn på nytt etter en feil. Å sende inn på nytt etter en timeout på din side er det ikke: poll den samme task_id først.

Slik beregnes den første regningen din

kling-4.0-image koster prisen per bilde ganger antall bilder, pluss 1 kreditt for hvert image_urls-element og hvert element, én gang per forespørsel. Med 1 kreditt = $0.005:

ForespørselKreditterUSD
Første cURL-kall ovenfor (2K, ett bilde)13$0.065
Samme prompt i 8K32$0.16
Elementredigeringen ovenfor (2K, 1 bilde + 1 element)15$0.075
Serie på fire 2K-bilder52$0.26
1K-nettside, uten referanser110$0.55
1K medium e-handelsside, 1 produktbilde95$0.475

Fullstendige tabeller og flere eksempler finner du i priser for Kling Image 4.0 API. For en oversikt over begge modell-ID-ene, se Hva er Kling Image 4.0.

Ofte stilte spørsmål

Hvordan kaller jeg Kling Image 4.0 API med Python? Send JSON-bodyen med POST til https://api.poyo.ai/api/generate/submit med requests, les data.task_id, og poll deretter /api/generate/status/{task_id} til finished og les files[].file_url. Løkken ovenfor gjør dette med tidsfrist og feilkontroller.

Hva er modell-ID-en til Kling Image 4.0 API? kling-4.0-image for tekst-til-bilde, redigeringer og bildeserier, og kling-4.0-long-image for lange nettsider og e-handelssider. kling-4-0-image er bare slug-en til siden.

Støtter Kling Image 4.0 API webhooks? Ja. Legg til callback_url på toppnivå i forespørselen. PoYo sender en signert POST når oppgaven er ferdig eller feiler.

Kan jeg få JPEG-output fra Kling Image 4.0 API? Det finnes ikke noe felt for outputformat; resultatene er PNG. Nedlastingene våre var RGBA-PNG-er selv for ugjennomsiktige bilder, så konverter på din side hvis du trenger JPEG.

Hvorfor kom den lange nettsiden min fra Kling Image 4.0 tilbake på et annet språk? Hvis prompten ikke oppgir språket for sideteksten, kan modellen velge ett selv. Oppgi det, for eksempel "All text on the page is in English."

Share: