API Kling Image 4.0 Long Image pour e-commerce et pages web
Générez des fiches produit e-commerce et pages web 1K ou 2K avec l’API Kling Image 4.0 Long Image : schémas, huit paliers tarifaires et délais.
Lire en MarkdownLes API d’images classiques montrent vite leurs limites dès que vous demandez une fiche produit e-commerce complète ou une maquette de page d’atterrissage multi-sections. Les formats plafonnent autour de 9:16 ou 21:9, la typographie dérive d’un bloc à l’autre et l’assemblage manuel de bannières laisse des raccords visibles. Kling Image 4.0 Long Image (kling-image-4-0-long-image) résout précisément ce workflow en générant toute une mise en page verticale sous la forme d’un unique PNG long cohérent depuis un seul appel POST /v1/images/generations.
Contrairement à Kling Image 4.0, qui produit des visuels 2K ou 4K distincts et des séries multi-plans, le point de terminaison Long Image repose sur deux modes spécialisés — ecommerce et webpage — chacun doté de ses propres types d’images de référence, réglages de longueur et paliers tarifaires. Fin novembre 2026, la plupart des résultats de recherche confondent encore ce modèle avec la vidéo Kling ou des upscalers génériques. Ce guide présente le contrat API vérifié, tous les paliers de prix, les règles de validation réelles et les bonnes pratiques de production pour gérer des rendus de plusieurs minutes et des PNG dépassant 50 Mo.
Deux modes, deux contrats d’entrée stricts
Chaque requête envoyée à kling-image-4-0-long-image doit déclarer settings.skill à ecommerce ou webpage. Mélanger les types de références entre les deux modes renvoie une erreur de validation HTTP 400 avant toute facturation.
| Champ / règle | skill: "ecommerce" | skill: "webpage" |
|---|---|---|
| Livrable principal | Fiche produit verticale (PDP) | Maquette visuelle complète de page web |
| Types d’éléments de référence | refer_image (obligatoire : 1 à 3 photos) | style_refer_image (0–1) et subject_refer_image (0–1) |
| Appels texte seul sans référence | Rejetés (HTTP 400) | Autorisés |
settings.length | short (~2–5 sections), medium (par défaut, ~6–10), long (~11–18) | Ignoré (à omettre) |
settings.resolution | 1k (1024 px de large, par défaut) ou 2k (2048 px de large) | 1k (1024 px de large, par défaut) ou 2k (2048 px de large) |
Résolution 4k | Non prise en charge (HTTP 400) | Non prise en charge (HTTP 400) |
| Nombre de sorties | Toujours 1 PNG long (output.data[0].url) | Toujours 1 PNG long (output.data[0].url) |
Chaque URL d’image de référence doit pointer vers un fichier JPEG ou PNG accessible publiquement en HTTP(S), jusqu’à 30 Mo, mesurant au moins 300 pixels par côté, avec un rapport largeur/hauteur compris entre 2:5 et 5:2. Notez que les références element ne sont pas prises en charge sur kling-image-4-0-long-image.
La capacité du prompt est particulièrement généreuse par rapport aux générateurs d’images classiques : jusqu’à 166 000 caractères anglais ou 71 000 caractères non anglais (les prompts mixtes doivent respecter english / 166000 + non_english / 71000 <= 1). Cette marge vous permet de fournir les textes complets section par section, les tableaux de spécifications vérifiés, les listes d’ingrédients et les légendes plutôt que de laisser le modèle inventer des caractéristiques produit.
Paliers tarifaires en direct et calcul des images de référence
Chaque tâche Long Image terminée facture un tarif forfaitaire par palier — déterminé par skill, resolution et (pour ecommerce) length — plus un tarif d’image de référence pour chaque photo d’entrée, dès la première image. Les requêtes échouées ou invalides ne sont pas facturées.
Combien coûte Kling Image 4.0 Long Image
| Catégorie | Tarifs (USD) |
|---|---|
| Ecommerce · 1K · court | $0.2269 |
| Ecommerce · 2K · court | $0.2723 |
| Ecommerce · 1K · moyen | $0.4538 |
| Ecommerce · 2K · moyen | $0.5294 |
| Ecommerce · 1K · long | $0.7563 |
| Ecommerce · 2K · long | $0.8319 |
| Webpage · 1K | $0.5294 |
| Webpage · 2K | $0.5748 |
| Image de référence | $0.003025 |
Sur https://api.toklab.ai/v1/pricing (vérifié le 20 novembre 2026), les huit paliers de sortie se répartissent comme suit, chaque image de référence en entrée ajoutant $0.003025 :
| Mode | Longueur | Résolution | Tarif de sortie | Exemple avec 2 références |
|---|---|---|---|---|
ecommerce | short (~2–5 sections) | 1k | $0.2269 | $0.23295 |
ecommerce | short (~2–5 sections) | 2k | $0.2723 | $0.27835 |
ecommerce | medium (~6–10 sections) | 1k | $0.4538 | $0.45985 |
ecommerce | medium (~6–10 sections) | 2k | $0.5294 | $0.53545 |
ecommerce | long (~11–18 sections) | 1k | $0.7563 | $0.76235 |
ecommerce | long (~11–18 sections) | 2k | $0.8319 | $0.83795 |
webpage | n/a | 1k | $0.5294 | $0.53545 |
webpage | n/a | 2k | $0.5748 | $0.58085 |
Regardez de près l’écart entre 1K et 2K : passer de 1k à 2k ajoute seulement $0.0454 en webpage (+8,6 %) et $0.0756 en ecommerce medium ou long (+10 % à +16,7 %). Comme les pages longues concentrent de petits libellés UI, des grilles techniques et du texte courant, le 2k (2048 px de large) vaut presque toujours ce faible supplément pour les livrables finaux, tandis que le 1k convient très bien pour des brouillons structurels peu coûteux avant de figer le plan.

Structurer ses prompts pour ecommerce vs webpage
Parce que le modèle compose toute la page déroulante en une seule passe, des prompts vagues produisent des sections de remplissage répétitives ou des spécifications inventées. Traiter le prompt comme un cahier des charges wireframe donne des résultats nettement plus propres :
- Listez les sections dans l’ordre exact de haut en bas. Numérotez explicitement chaque bandeau — par exemple :
Section 1 : Bannière principale,Section 2 : 3 colonnes d’atouts,Section 3 : Macro texture,Section 4 : Tableau de spécifications,Section 5 : Conseils d’entretien et pied de page. - Ancrez chaque photo de référence avec
@id. En modeecommerce, donnez des IDs explicites (front,spout,box) et indiquez quel bandeau utilise quel angle. En modewebpage, séparez la direction visuelle (@layoutviastyle_refer_image) de l’objet phare (@productviasubject_refer_image). - Fournissez les textes et chiffres exacts. N’écrivez jamais « ajoutez des caractéristiques techniques réalistes ». Donnez la puissance, les dimensions, les matériaux et les titres exacts à afficher pour éviter de retoucher des valeurs inventées.
- Alignez
settings.lengthsur votre nombre de sections. Demander 14 bandeaux détaillés aveclength: "short"comprime la typographie jusqu’à rendre les petits libellés flous. Associez 2–5 bandeaux àshort, 6–10 àmediumet 11–18 àlong.
Choisir le bon palier de longueur e-commerce
Choisir entre short, medium et long relève autant du rythme visuel que du budget. Une page short (~2–5 sections, $0.2269 en 1k ou $0.2723 en 2k) convient aux cartes promotionnelles mono-SKU, aux teasers mobile-first et aux bandeaux comparatifs où l’acheteur n’a besoin que d’un visuel principal, de trois arguments et d’un bloc technique compact. Une page medium (~6–10 sections, $0.4538 en 1k ou $0.5294 en 2k) représente le meilleur équilibre pour la plupart des boutiques Shopify, Amazon A+ et e-commerce transfrontaliers : elle offre assez de hauteur pour un visuel principal, des gros plans matières, des mises en situation, un tableau de dimensions et le contenu de la boîte sans diluer le propos.
Réservez long (~11–18 sections, $0.7563 en 1k ou $0.8319 en 2k) à l’électronique phare, à l’électroménager ou aux kits multi-variantes qui nécessitent réellement des bandeaux narratifs, des vues éclatées annotées, des guides pas à pas, des badges de certification et une FAQ. Si vous manquez de faits produit distincts pour remplir onze sections ou plus, le mode long tend à répéter des angles déjà vus ou à inventer des bannières lifestyle génériques, gaspillant temps de rendu et budget.
Pourquoi le mode webpage sépare références de style et de sujet
En mode webpage, séparer style_refer_image et subject_refer_image évite un défaut classique des API à référence unique : voir le modèle copier le produit d’une autre marque dans votre maquette, ou importer l’arrière-plan encombré de votre photo produit dans l’interface du site. Passer une capture éditoriale ou un cadre Figma dans style_refer_image le cantonne au rythme de grille, aux couleurs, à la hiérarchie typographique et au style des boutons, tandis qu’une photo studio propre dans subject_refer_image garde l’objet fidèle du bloc principal aux cartes produit. Si vous voulez une direction artistique originale à partir du texte seul, omettez les deux champs d’image et décrivez palette, typographies et grille directement dans le prompt.
Contrôle qualité avant publication des pages générées
Même en résolution 2k, les images longues générées doivent passer une vérification rapide automatisée et visuelle avant mise en ligne sur une boutique ou une présentation client. D’abord, contrôlez chaque chiffre, unité et ligne d’ingrédients par rapport au prompt source — les petites coquilles typographiques dans les tableaux denses se repèrent bien plus facilement à 100 % que sur un aperçu réduit. Ensuite, vérifiez que la géométrie physique du produit (emplacement des boutons, logos, ports et proportions) reste cohérente du bandeau principal jusqu’aux gros plans. Enfin, vérifiez la lisibilité verticale sur un écran mobile de 390 px après découpage : une rangée desktop dense de 4 colonnes très nette en 2 048 px peut devenir illisible sur smartphone à moins de demander des cartes 2 colonnes ou empilées à fort contraste.
Exemples complets de requêtes pour les deux modes
1. Fiche produit e-commerce (medium, 2k)
{
"model": "kling-image-4-0-long-image",
"contents": [
{"type": "refer_image", "url": "https://example.com/kettle-front.png", "id": "front"},
{"type": "refer_image", "url": "https://example.com/kettle-spout.jpg", "id": "spout"},
{
"type": "prompt",
"text": "Design a clean ecommerce product detail page for the matte black gooseneck kettle in @front. Section 1: Hero banner with headline 'Precision Pour 0.9L' and @front centered on warm stone. Section 2: Three feature cards covering 1200W rapid boil, 1-degree PID control, and 60-minute hold. Section 3: Macro close-up based on @spout highlighting laminar flow control. Section 4: Lifestyle pour-over brewing scene. Section 5: Dimension and electrical spec table (900 ml, 1200W, 120V, 304 stainless steel). Section 6: Box contents and care notes."
}
],
"settings": {
"skill": "ecommerce",
"length": "medium",
"resolution": "2k"
}
}2. Design visuel de page web avec références de style + sujet (2k)
import os
import time
import requests
API_KEY = os.environ["TOKLAB_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "kling-image-4-0-long-image",
"contents": [
{"type": "style_refer_image", "url": "https://example.com/editorial-grid.png", "id": "grid"},
{"type": "subject_refer_image", "url": "https://example.com/chronograph.jpg", "id": "watch"},
{
"type": "prompt",
"text": (
"Create a vertical product launch webpage adopting the Swiss editorial grid, "
"high-contrast serif headings, and generous whitespace of @grid while featuring @watch. "
"Include: top navigation bar, full-bleed hero with @watch, three-card movement breakdown, "
"water-resistance specification band, and minimalist footer."
),
},
],
"settings": {"skill": "webpage", "resolution": "2k"},
}
resp = requests.post(
"https://api.toklab.ai/v1/images/generations",
headers=HEADERS,
json=payload,
timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["id"]
# Poll every 5s; long 2K layouts can take several minutes.
deadline = time.time() + 600
while time.time() < deadline:
status_resp = requests.get(
f"https://api.toklab.ai/v1/tasks/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
status_resp.raise_for_status()
data = status_resp.json()
if data.get("status") == "completed":
png_url = data["output"]["data"][0]["url"]
print("Ready:", png_url)
break
if data.get("status") == "failed":
raise RuntimeError(f"Long image task failed: {data}")
time.sleep(5)Notes d’ingénierie en production : timeouts, PNG > 50 Mo et découpage
Intégrer kling-image-4-0-long-image dans un service backend diffère d’un générateur rapide en 1024×1024 sur trois points opérationnels :
- Prévoyez une latence de plusieurs minutes. Un rendu e-commerce
long+2kprend couramment plusieurs minutes. Ne maintenez pas une requête HTTP ouverte depuis un navigateur ou une fonction serverless limitée à 30 secondes ; mettez letask_iden file dans un worker d’arrière-plan et interrogezGET /v1/tasks/:idavec un plafond de 10 minutes. - Téléchargez les gros PNG en streaming. Comme une image longue
2kfait 2 048 pixels de large et peut atteindre 10 000 à 20 000+ pixels de haut, les fichiers PNG finaux peuvent dépasser 50 Mo. Utilisez des téléchargements en flux (requests.get(url, stream=True)) avec des timeouts de lecture généreux et évitez de charger plusieurs bitmaps bruts en mémoire dans un petit conteneur. - Découpez et réencodez pour la production e-commerce. Les plateformes (Shopify, Amazon A+, Taobao/Tmall) et les navigateurs mobiles pénalisent les PNG uniques de 50 Mo. Après validation de la mise en page, découpez le PNG master le long des limites de sections et convertissez chaque tranche en WebP ou JPEG progressif à 80–85 % de qualité pour un chargement rapide.
Erreurs HTTP 400 fréquentes à anticiper
Validez ces cinq conditions avant d’appeler le point de terminaison :
- Absence de
settings.skill(doit être"ecommerce"ou"webpage"). skill: "ecommerce"avec zéro élémentrefer_imageou plus de trois.- Envoi de
refer_imageen modewebpage, ou destyle_refer_image/subject_refer_imageen modeecommerce. - Demande de
resolution: "4k"(seuls"1k"et"2k"existent pour Long Image). - Réutilisation du même
idsur deux éléments de référence danscontents.
Si votre workflow demande des visuels de campagne horizontaux ou carrés, des séries lifestyle produit ou jusqu’à 10 images de référence dans un même cadre, dirigez ces tâches vers Kling Image 4.0 et réservez Kling Image 4.0 Long Image aux compositions verticales multi-sections.
Sources
- Page modèle TokLab Kling Image 4.0 Long Image — Playground interactif, grille tarifaire 1K/2K en direct et calculateur.
- Référence API TokLab Kling Image 4.0 Long Image — Schéma officiel, limites de caractères et contraintes de validation.
- API Tarifs en direct TokLab — Flux tarifaire lisible par machine vérifié le 20 novembre 2026.


