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 Markdown

Les 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ègleskill: "ecommerce"skill: "webpage"
Livrable principalFiche produit verticale (PDP)Maquette visuelle complète de page web
Types d’éléments de référencerefer_image (obligatoire : 1 à 3 photos)style_refer_image (0–1) et subject_refer_image (0–1)
Appels texte seul sans référenceRejetés (HTTP 400)Autorisés
settings.lengthshort (~2–5 sections), medium (par défaut, ~6–10), long (~11–18)Ignoré (à omettre)
settings.resolution1k (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 4kNon prise en charge (HTTP 400)Non prise en charge (HTTP 400)
Nombre de sortiesToujours 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égorieTarifs (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 :

ModeLongueurRésolutionTarif de sortieExemple avec 2 références
ecommerceshort (~2–5 sections)1k$0.2269$0.23295
ecommerceshort (~2–5 sections)2k$0.2723$0.27835
ecommercemedium (~6–10 sections)1k$0.4538$0.45985
ecommercemedium (~6–10 sections)2k$0.5294$0.53545
ecommercelong (~11–18 sections)1k$0.7563$0.76235
ecommercelong (~11–18 sections)2k$0.8319$0.83795
webpagen/a1k$0.5294$0.53545
webpagen/a2k$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.

Fiche produit e-commerce Kling Image 4.0 Long Image générée sur TokLab

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 :

  1. 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.
  2. Ancrez chaque photo de référence avec @id. En mode ecommerce, donnez des IDs explicites (front, spout, box) et indiquez quel bandeau utilise quel angle. En mode webpage, séparez la direction visuelle (@layout via style_refer_image) de l’objet phare (@product via subject_refer_image).
  3. 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.
  4. Alignez settings.length sur votre nombre de sections. Demander 14 bandeaux détaillés avec length: "short" comprime la typographie jusqu’à rendre les petits libellés flous. Associez 2–5 bandeaux à short, 6–10 à medium et 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 + 2k prend couramment plusieurs minutes. Ne maintenez pas une requête HTTP ouverte depuis un navigateur ou une fonction serverless limitée à 30 secondes ; mettez le task_id en file dans un worker d’arrière-plan et interrogez GET /v1/tasks/:id avec un plafond de 10 minutes.
  • Téléchargez les gros PNG en streaming. Comme une image longue 2k fait 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 :

  1. Absence de settings.skill (doit être "ecommerce" ou "webpage").
  2. skill: "ecommerce" avec zéro élément refer_image ou plus de trois.
  3. Envoi de refer_image en mode webpage, ou de style_refer_image / subject_refer_image en mode ecommerce.
  4. Demande de resolution: "4k" (seuls "1k" et "2k" existent pour Long Image).
  5. Réutilisation du même id sur deux éléments de référence dans contents.

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

Guides associés