
Dieser Kling Image 4.0 API Guide führt Sie vom API-Schlüssel zum fertigen Bild: ein cURL-Aufruf, eine begrenzte Python-Polling-Schleife und dann ein funktionierender JSON-Body für jeden Eingabemodus von kling-4.0-image und kling-4.0-long-image. Probieren Sie jeden davon zuerst im Kling Image 4.0 Playground aus; jeder Request-Body unten folgt der PoYo-Dokumentation.
Ihr erster Request an die Kling Image 4.0 API mit cURL
Erstellen Sie im PoYo-Dashboard einen Schlüssel und bewahren Sie ihn auf Ihrem Server als POYO_API_KEY auf. Senden Sie dann einen 2K-Text-zu-Bild-Task:
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"
}
}'
Die Antwort enthält code: 200 und data.task_id, mit status: "not_started". Ein eingereichter Task ist noch kein fertiges Bild. Prüfen Sie ihn mit:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Die Status sind not_started, running, finished und failed. Bei finished enthält data.files einen Eintrag pro Bild mit file_url und file_type: "image", und data.credits_amount zeigt, was der Task gekostet hat. Bei failed lesen Sie data.error_message.
Eine begrenzte Python-Polling-Schleife
Dieser Code läuft auf Ihrem Backend mit requests. Er prüft sowohl den HTTP-Status als auch das Feld code im Body (Validierungsfehler können als HTTP 200 mit code: 400 ankommen), stoppt bei failed und hört nach 20 Minuten auf zu warten, ohne erneut einzureichen, denn ein zweiter Submit ist eine zweite Rechnung.
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)
Für lange Jobs fügen Sie dem Payload stattdessen ein "callback_url": "https://your-domain.com/poyo-hook" auf oberster Ebene hinzu. PoYo sendet dieselben Task-Daten (ohne die code/data-Hülle) per POST, wenn der Task abgeschlossen ist oder fehlschlägt, signiert mit HMAC-SHA256 in X-Webhook-Signature; die Webhook-Dokumentation zeigt, wie Sie die Signatur prüfen.
Bild-zu-Bild mit image_urls
Übergeben Sie 1 bis 10 öffentliche HTTP(S)-URLs in image_urls. Die erste ist @Image1, die zweite @Image2, in der Reihenfolge des Arrays. Geben Sie jeder im Prompt eine Rolle und sagen Sie, was unverändert bleiben muss.
{
"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 muss auch für ein einzelnes Bild ein Array sein. Jedes Bild darf höchstens 30 MB groß sein, muss mindestens 300 px breit und hoch sein und ein Breite/Höhe-Verhältnis zwischen 0.4 und 2.5 haben.
Konsistente Motive mit kling_elements
Ein Element ist eine Figur oder ein Objekt, gezeigt aus 2 bis 4 Blickwinkeln, die Frontalansicht zuerst. Elemente brauchen mindestens einen image_urls-Eintrag, und Sie können bis zu 7 davon übergeben; Bilder plus Elemente sind auf 10 begrenzt.
{
"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"
}
}
Dieser Request kostet 13 Credits für das 2K-Bild plus 1 für das Referenzbild und 1 für das Element: 15 Credits ($0.075).
Bildserien mit enable_sequential
Mit enable_sequential: true reicht n von 2 bis 10 (Standard 4), und das Modell plant die Bilder als eine Serie mit denselben Motiven und demselben Stil, in Reihenfolge zurückgegeben. Ist die Option aus, liefert n von 1 bis 9 unabhängige 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
}
}
In unserem Test am Launch-Tag (PoYo-Produktions-API, 19. November 2026) lieferte eine 16:9-Serie in 2K mit n: 4 vier 2720×1536-Bilder mit demselben Fahrer, demselben Motorrad und Outfit über Morgendämmerung, Mittag, Sonnenuntergang und Nacht. Sie kostet 52 Credits, und es dauerte vom Submit bis zum Ergebnis etwa 4.9 Minuten.
Lange Webseiten und E-Commerce-Seiten
Wechseln Sie die Modell-ID zu kling-4.0-long-image und wählen Sie einen skill. Ein Webseitendesign, optional nach einer Stilreferenz:
{
"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"
}
}
Eine E-Commerce-Detailseite aus einem 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"
}
}
Tipp: Nennen Sie die Sprache der Seite. In unserem Test kam ein englischer Webpage-Prompt, der nicht sagte, in welcher Sprache der Text stehen soll, mit chinesischem Text auf der Seite zurück. Der Zusatz "All text on the page is in English." im Prompt hat das behoben, deshalb enden beide Bodies oben mit dieser Zeile. Unser 1K-Webpage-Test lieferte ein 1024×4257-Bild für 110 Credits in etwa 1.7–2.2 Minuten.
image_urls und length gehören zu ecommerce; style_image_url und subject_image_url gehören zu webpage. Mehr zu Seitenlängen und 8K-Ausgabe in 8K und lange Bilder mit der Kling Image 4.0 API.
Die Ergebnisse speichern
Jede files[].file_url zeigt auf ein PNG. Kopieren Sie es in Ihren eigenen Speicher, statt es aus Ihrer App per Hotlink einzubinden. Drei Punkte aus unserem Lauf am Launch-Tag, die Sie einplanen sollten:
- Größe. Ein 16:9-Bild in 8K war ein 10880×6144-PNG von etwa 128 MB. Streamen Sie es auf die Festplatte, statt es in den Speicher zu laden, und erhöhen Sie das Read-Timeout Ihres Clients.
- Alphakanal. Die Downloads waren RGBA-PNGs, auch bei deckenden Bildern. Wenn Ihre Pipeline, Ihr CDN oder Ihr Druck-Workflow RGB oder JPEG erwartet, konvertieren Sie nach dem Download.
- Reihenfolge. Eine Bildserie kommt in Reihenfolge zurück, der Index in
filesist also die Frame-Nummer Ihres Storyboards oder Foliensatzes.
Validierungsregeln, die Sie vor dem Submit prüfen sollten
| Regel | Modell |
|---|---|
prompt 1–50,000 Zeichen, nicht nur Leerzeichen | beide |
image_urls 1–10 Einträge; je 30 MB, ≥300 px, Verhältnis 0.4–2.5 | kling-4.0-image |
kling_elements ≤ 7, je 2–4 URLs, nur mit image_urls; Bilder + Elemente ≤ 10 | kling-4.0-image |
n 1–9 ohne Serie, 2–10 mit enable_sequential: true | kling-4.0-image |
resolution 2K / 4K / 8K | kling-4.0-image |
skill: "ecommerce" braucht 1–3 image_urls; resolution 1K / 2K | kling-4.0-long-image |
Keine zusätzlichen Felder (output_format, seed, negative_prompt werden abgelehnt) | beide |
Fehler, die Sie behandeln sollten
code | Bedeutung | Was tun |
|---|---|---|
| 400 | Ungültige Parameter | Body korrigieren; nicht unverändert wiederholen |
| 401 | Fehlender oder ungültiger API-Schlüssel | Header prüfen |
| 402 | Nicht genügend Credits | Aufladen, dann erneut einreichen |
| 429 | Rate Limit | Zurückfahren und später erneut versuchen |
| 500 / 502 / 503 | Server- oder Upstream-Fehler | Submit mit Backoff wiederholen |
Ein failed-Task wird nicht berechnet, ein erneutes Einreichen nach einem Fehlschlag ist also unbedenklich. Ein erneutes Einreichen nach einem Timeout auf Ihrer Seite nicht: Fragen Sie zuerst dieselbe task_id erneut ab.
So wird Ihre erste Rechnung berechnet
kling-4.0-image kostet den Preis pro Bild mal die Anzahl der Bilder, plus 1 Credit für jeden image_urls-Eintrag und jedes Element, einmal pro Request. Bei 1 Credit = $0.005:
| Request | Credits | USD |
|---|---|---|
| Erster cURL-Aufruf oben (2K, ein Bild) | 13 | $0.065 |
| Derselbe Prompt in 8K | 32 | $0.16 |
| Element-Edit oben (2K, 1 Bild + 1 Element) | 15 | $0.075 |
| 2K-Serie aus vier Bildern | 52 | $0.26 |
| 1K-Webseite, ohne Referenzen | 110 | $0.55 |
| 1K-E-Commerce-Seite medium, 1 Produktfoto | 95 | $0.475 |
Vollständige Tabellen und weitere Beispiele finden Sie unter Kling Image 4.0 API Preise. Einen Überblick über beide Modell-IDs gibt Was ist Kling Image 4.0.
Häufig gestellte Fragen
Wie rufe ich die Kling Image 4.0 API mit Python auf?
Senden Sie den JSON-Body mit requests per POST an https://api.poyo.ai/api/generate/submit, lesen Sie data.task_id und fragen Sie dann /api/generate/status/{task_id} ab, bis der Status finished ist, und lesen Sie files[].file_url. Die Schleife oben erledigt das mit Frist und Fehlerprüfung.
Wie lautet die Modell-ID der Kling Image 4.0 API?
kling-4.0-image für Text-zu-Bild, Edits und Bildserien, und kling-4.0-long-image für lange Webseiten und E-Commerce-Seiten. kling-4-0-image ist nur der Slug der Seite.
Unterstützt die Kling Image 4.0 API Webhooks?
Ja. Fügen Sie callback_url auf oberster Ebene des Requests hinzu. PoYo sendet einen signierten POST, wenn der Task abgeschlossen ist oder fehlschlägt.
Kann ich von der Kling Image 4.0 API JPEG-Ausgabe bekommen? Es gibt kein Feld für das Ausgabeformat; die Ergebnisse sind PNG. Unsere Downloads waren RGBA-PNGs, auch bei deckenden Bildern, konvertieren Sie also auf Ihrer Seite, wenn Sie JPEG brauchen.
Warum kam meine lange Kling Image 4.0 Webseite in einer anderen Sprache zurück? Wenn der Prompt die Sprache des Seitentexts nicht nennt, wählt das Modell möglicherweise selbst eine. Geben Sie sie an, zum Beispiel "All text on the page is in English."