
Ce guide de la Kling Image 4.0 API vous mène d’une clé API à une image terminée : un appel cURL, une boucle de polling Python bornée, puis un corps JSON fonctionnel pour chaque mode d’entrée de kling-4.0-image et kling-4.0-long-image. Essayez-les d’abord dans le playground Kling Image 4.0 ; chaque corps de requête ci-dessous suit la documentation PoYo.
Votre première requête à la Kling Image 4.0 API avec cURL
Créez une clé dans le tableau de bord PoYo et conservez-la sur votre serveur sous le nom POYO_API_KEY. Soumettez ensuite une tâche texte vers image en 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"
}
}'
La réponse contient code: 200 et data.task_id, avec status: "not_started". Une tâche soumise n’est pas une image terminée. Vérifiez-la avec :
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Les statuts sont not_started, running, finished et failed. En finished, data.files contient une entrée par image avec file_url et file_type: "image", et data.credits_amount indique le coût de la tâche. En failed, lisez data.error_message.
Une boucle de polling Python bornée
Ce code s’exécute sur votre backend avec requests. Il vérifie à la fois le statut HTTP et le champ code du corps (les erreurs de validation peuvent arriver en HTTP 200 avec code: 400), s’arrête sur failed et cesse d’attendre au bout de 20 minutes sans resoumettre, car une seconde soumission est une seconde facture.
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)
Pour les tâches longues, ajoutez plutôt un "callback_url": "https://your-domain.com/poyo-hook" au premier niveau du payload. PoYo envoie en POST les mêmes données de tâche (sans l’enveloppe code/data) lorsque la tâche se termine ou échoue, signées en HMAC-SHA256 dans X-Webhook-Signature ; la documentation des webhooks explique comment les vérifier.
Image vers image avec image_urls
Passez 1 à 10 URL HTTP(S) publiques dans image_urls. La première est @Image1, la deuxième @Image2, dans l’ordre du tableau. Donnez un rôle à chacune dans le prompt et dites ce qui doit rester inchangé.
{
"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 doit être un tableau, même pour une seule image. Chaque image doit faire au plus 30 MB, au moins 300 px de large et de haut, avec un ratio largeur/hauteur compris entre 0.4 et 2.5.
Des sujets cohérents avec kling_elements
Un element est un personnage ou un objet montré sous 2 à 4 angles, vue de face en premier. Les elements nécessitent au moins une entrée dans image_urls, et vous pouvez en passer jusqu’à 7 ; images plus elements sont plafonnés à 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"
}
}
Cette requête coûte 13 crédits pour l’image 2K, plus 1 pour l’image de référence et 1 pour l’element : 15 crédits ($0.075).
Séries d’images avec enable_sequential
Avec enable_sequential: true, n va de 2 à 10 (4 par défaut) et le modèle conçoit les images comme une seule série, avec les mêmes sujets et le même style, renvoyées dans l’ordre. Sans cette option, n de 1 à 9 renvoie des images indépendantes.
{
"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
}
}
Lors de notre test du jour du lancement (API de production PoYo, 19 novembre 2026), une série 16:9 en 2K avec n: 4 a renvoyé quatre images 2720×1536 avec le même pilote, la même moto et la même tenue à l’aube, à midi, au coucher du soleil et la nuit. Elle coûte 52 crédits et a pris environ 4.9 minutes de la soumission au résultat.
Pages web longues et pages e-commerce
Passez l’identifiant de modèle à kling-4.0-long-image et choisissez un skill. Un design de page web, qui suit éventuellement une référence de style :
{
"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"
}
}
Une page produit e-commerce à partir d’une photo produit :
{
"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"
}
}
Astuce : précisez la langue de la page. Lors de notre test, un prompt de page web en anglais qui ne disait pas dans quelle langue rédiger le texte est revenu avec du texte en chinois sur la page. Ajouter « All text on the page is in English. » au prompt a réglé le problème, c’est pourquoi les deux corps ci-dessus se terminent par cette phrase. Notre test de page web en 1K a renvoyé une image 1024×4257 pour 110 crédits en environ 1.7–2.2 minutes.
image_urls et length appartiennent à ecommerce ; style_image_url et subject_image_url appartiennent à webpage. Plus d’informations sur les longueurs de page et la sortie 8K dans 8K et images longues avec la Kling Image 4.0 API.
Enregistrer les résultats
Chaque files[].file_url pointe vers un PNG. Copiez-le dans votre propre stockage au lieu de le lier directement depuis votre application. Trois points de notre test du jour du lancement à anticiper :
- Taille. Une image 8K en 16:9 était un PNG 10880×6144 d’environ 128 MB. Écrivez-la en streaming sur disque au lieu de la charger en mémoire, et augmentez le délai de lecture de votre client.
- Canal alpha. Les fichiers téléchargés étaient des PNG RGBA, même pour des images opaques. Si votre pipeline, votre CDN ou votre flux d’impression attend du RGB ou du JPEG, convertissez après le téléchargement.
- Ordre. Une série d’images est renvoyée dans l’ordre : l’index dans
filescorrespond donc au numéro de plan de votre storyboard ou de votre série de slides.
Règles de validation à vérifier avant de soumettre
| Règle | Modèle |
|---|---|
prompt de 1–50,000 caractères, pas uniquement des espaces | les deux |
image_urls de 1–10 éléments ; 30 MB, ≥300 px, ratio 0.4–2.5 chacun | kling-4.0-image |
kling_elements ≤ 7, chacun avec 2–4 URL, uniquement avec image_urls ; images + elements ≤ 10 | kling-4.0-image |
n de 1–9 sans série, 2–10 avec enable_sequential: true | kling-4.0-image |
resolution 2K / 4K / 8K | kling-4.0-image |
skill: "ecommerce" nécessite 1–3 image_urls ; resolution 1K / 2K | kling-4.0-long-image |
Aucun champ supplémentaire (output_format, seed, negative_prompt sont rejetés) | les deux |
Erreurs à gérer
code | Signification | Que faire |
|---|---|---|
| 400 | Paramètres invalides | Corrigez le corps ; ne relancez pas à l’identique |
| 401 | Clé API manquante ou invalide | Vérifiez l’en-tête |
| 402 | Crédits insuffisants | Rechargez, puis resoumettez |
| 429 | Limite de débit | Patientez et réessayez plus tard |
| 500 / 502 / 503 | Erreur serveur ou fournisseur amont | Relancez la soumission avec un backoff |
Une tâche failed n’est pas facturée : resoumettre après un échec est donc sans risque. Resoumettre après un timeout de votre côté ne l’est pas : interrogez d’abord le même task_id.
Comment se calcule votre première facture
kling-4.0-image coûte le prix par image multiplié par le nombre d’images, plus 1 crédit pour chaque élément de image_urls et chaque element, une fois par requête. À 1 crédit = $0.005 :
| Requête | Crédits | USD |
|---|---|---|
| Premier appel cURL ci-dessus (2K, une image) | 13 | $0.065 |
| Même prompt en 8K | 32 | $0.16 |
| Édition avec element ci-dessus (2K, 1 image + 1 element) | 15 | $0.075 |
| Série de quatre images 2K | 52 | $0.26 |
| Page web 1K, sans référence | 110 | $0.55 |
| Page e-commerce medium 1K, 1 photo produit | 95 | $0.475 |
Tableaux complets et autres exemples dans Prix de la Kling Image 4.0 API. Pour une vue d’ensemble des deux identifiants de modèle, voir Qu’est-ce que Kling Image 4.0.
Questions fréquentes
Comment appeler la Kling Image 4.0 API en Python ?
Envoyez le corps JSON en POST à https://api.poyo.ai/api/generate/submit avec requests, lisez data.task_id, puis interrogez /api/generate/status/{task_id} jusqu’à finished et lisez files[].file_url. La boucle ci-dessus le fait avec une échéance et des contrôles d’erreur.
Quel est l’identifiant de modèle de la Kling Image 4.0 API ?
kling-4.0-image pour le texte vers image, les éditions et les séries d’images, et kling-4.0-long-image pour les pages web longues et les pages e-commerce. kling-4-0-image n’est que le slug de la page.
La Kling Image 4.0 API prend-elle en charge les webhooks ?
Oui. Ajoutez callback_url au premier niveau de la requête. PoYo envoie un POST signé lorsque la tâche se termine ou échoue.
Puis-je obtenir du JPEG avec la Kling Image 4.0 API ? Il n’existe aucun champ de format de sortie ; les résultats sont en PNG. Nos fichiers téléchargés étaient des PNG RGBA, même pour des images opaques : convertissez de votre côté si vous avez besoin de JPEG.
Pourquoi ma page web longue Kling Image 4.0 est-elle revenue dans une autre langue ? Si le prompt ne précise pas la langue du texte de la page, le modèle peut en choisir une. Indiquez-la, par exemple « All text on the page is in English. »