API Kling Image 4.0 Long Image per ecommerce e pagine web
Genera pagine dettaglio ecommerce e design web verticali in 1K o 2K con Kling Image 4.0 Long Image API: schemi delle due skill, fasce di prezzo e timeout.
Leggi in MarkdownLe API immagini standard vanno in crisi appena chiedi un'intera pagina dettaglio prodotto ecommerce scorrevole o un mockup di landing page a più sezioni. Le proporzioni si fermano attorno a 9:16 o 21:9, la tipografia cambia tra un ritaglio e l'altro e cucire insieme banner separati lascia giunture visibili. Kling Image 4.0 Long Image (kling-image-4-0-long-image) risolve esattamente questo flusso renderizzando un intero layout verticale come un unico PNG alto e coerente da una sola chiamata POST /v1/images/generations.
A differenza di Kling Image 4.0, che produce immagini statiche 2K o 4K e serie multi-fotogramma, l'endpoint Long Image ruota attorno a due skill di layout specializzate — ecommerce e webpage — ciascuna con propri tipi di immagini di riferimento, controlli di lunghezza e prezzi a fasce. A fine novembre 2026 la maggior parte dei risultati di ricerca confonde ancora questo modello con i video Kling o con generici upscaler. Questa guida raccoglie il contratto API verificato, tutte le fasce di prezzo, le regole reali di validazione e i dettagli di ingegneria di produzione necessari per gestire in modo pulito render da diversi minuti e download PNG oltre i 50 MB.
Due skill, due contratti di input rigorosi
Ogni richiesta a kling-image-4-0-long-image deve dichiarare settings.skill come ecommerce oppure webpage. Mescolare i tipi di riferimento tra le due modalità restituisce un errore di validazione HTTP 400 prima di qualsiasi addebito.
| Campo / regola | skill: "ecommerce" | skill: "webpage" |
|---|---|---|
| Deliverable principale | Pagina dettaglio prodotto verticale (PDP) | Design visivo di pagina web scorrevole |
| Tipi di elemento riferimento | refer_image (obbligatorio: da 1 a 3 foto) | style_refer_image (0–1) e subject_refer_image (0–1) |
| Chiamate solo testo senza riferimenti | Respinte (HTTP 400) | Consentite |
settings.length | short (~2–5 sezioni), medium (predefinito, ~6–10), long (~11–18) | Ignorato (omettere) |
settings.resolution | 1k (1024 px di larghezza, predefinito) o 2k (2048 px) | 1k (1024 px di larghezza, predefinito) o 2k (2048 px) |
Risoluzione 4k | Non supportata (HTTP 400) | Non supportata (HTTP 400) |
| Numero di output | Sempre 1 PNG verticale (output.data[0].url) | Sempre 1 PNG verticale (output.data[0].url) |
Ogni URL di immagine di riferimento deve puntare a un JPEG o PNG accessibile pubblicamente via HTTP(S) fino a 30 MB, di almeno 300 pixel per lato, con rapporto larghezza/altezza tra 2:5 e 5:2. Nota che i riferimenti di tipo element non sono supportati su kling-image-4-0-long-image.
La capacità del prompt è insolitamente ampia rispetto ai generatori standard: fino a 166.000 caratteri inglesi o 71.000 caratteri non inglesi (i prompt misti devono soddisfare english / 166000 + non_english / 71000 <= 1). Questo margine esiste per consentirti di fornire testi completi sezione per sezione, tabelle specifiche verificate, elenchi di ingredienti ed etichette di callout anziché lasciare che il modello inventi caratteristiche del prodotto.
Fasce di prezzo dal vivo e calcolo dei riferimenti
Ogni attività Long Image completata addebita una tariffa fissa di fascia — determinata da skill, resolution e (per ecommerce) length — più una tariffa per immagine di riferimento per ciascuna foto in input, a partire dalla prima. Le richieste fallite o non valide non comportano alcun addebito.
Quanto costa Kling Image 4.0 Long Image
| Categoria | Prezzi (USD) |
|---|---|
| Ecommerce · 1K · short | $0.2269 |
| Ecommerce · 2K · short | $0.2723 |
| Ecommerce · 1K · medium | $0.4538 |
| Ecommerce · 2K · medium | $0.5294 |
| Ecommerce · 1K · long | $0.7563 |
| Ecommerce · 2K · long | $0.8319 |
| Webpage · 1K | $0.5294 |
| Webpage · 2K | $0.5748 |
| Immagine di riferimento | $0.003025 |
Su https://api.toklab.ai/v1/pricing (verificato il 20 novembre 2026), le otto fasce di output si ripartiscono come segue, con ogni immagine di riferimento in input che aggiunge $0.003025:
| Skill | Lunghezza | Risoluzione | Tariffa output | Esempio con 2 riferimenti |
|---|---|---|---|---|
ecommerce | short (~2–5 sezioni) | 1k | $0.2269 | $0.23295 |
ecommerce | short (~2–5 sezioni) | 2k | $0.2723 | $0.27835 |
ecommerce | medium (~6–10 sezioni) | 1k | $0.4538 | $0.45985 |
ecommerce | medium (~6–10 sezioni) | 2k | $0.5294 | $0.53545 |
ecommerce | long (~11–18 sezioni) | 1k | $0.7563 | $0.76235 |
ecommerce | long (~11–18 sezioni) | 2k | $0.8319 | $0.83795 |
webpage | n/d | 1k | $0.5294 | $0.53545 |
webpage | n/d | 2k | $0.5748 | $0.58085 |
Osserva da vicino il salto da 1K a 2K: passare da 1k a 2k aggiunge appena $0.0454 su webpage (+8,6%) e $0.0756 su ecommerce medium o long (+10% fino a +16,7%). Poiché le pagine verticali racchiudono etichette UI piccole, griglie di specifiche e testi di corpo, 2k (2048 px di larghezza) vale quasi sempre il piccolo sovrapprezzo per gli asset finali, mentre 1k funziona bene per bozze strutturali economiche prima di bloccare la scaletta delle sezioni.

Come strutturare i prompt per ecommerce vs webpage
Poiché il modello compone un'intera pagina scorrevole in un solo passaggio, prompt vaghi generano sezioni riempitive ripetitive o specifiche inventate. Trattare il prompt come una specifica di wireframe produce layout molto più puliti:
- Elenca le sezioni nell'ordine esatto dall'alto verso il basso. Numera esplicitamente ogni fascia — ad esempio:
Section 1: Hero banner,Section 2: 3-column feature callouts,Section 3: Macro texture detail,Section 4: Specification table,Section 5: Care instructions and footer. - Ancora ogni foto di riferimento con
@id. In modalitàecommerce, assegna ID chiari (front,spout,box) e indica al modello in quale fascia inserire ciascuna angolazione. In modalitàwebpage, separa stile e impaginazione (@layouttramitestyle_refer_image) dall'oggetto principale (@producttramitesubject_refer_image). - Fornisci testi e numeri esatti. Non scrivere mai "aggiungi specifiche tecniche realistiche". Indica wattaggio, dimensioni, materiali e titoli esatti che vuoi renderizzare, così non dovrai ritoccare dati inventati in seguito.
- Allinea
settings.lengthal numero di sezioni. Chiedere 14 fasce dettagliate dentrolength: "short"comprime la tipografia fino a rendere sfocate le etichette piccole. Abbina 2–5 fasce ashort, 6–10 amediume 11–18 along.
Scegliere la fascia di lunghezza ecommerce corretta
Scegliere tra short, medium e long è sia una decisione di ritmo visivo sia una leva di budget. Una pagina short (~2–5 sezioni, $0.2269 a 1k o $0.2723 a 2k) si adatta a schede promozionali per singolo SKU, anteprime mobile-first su marketplace e fasce comparative dove l'acquirente ha bisogno solo di uno scatto hero, tre punti di forza e un blocco specifiche compatto. Una pagina medium (~6–10 sezioni, $0.4538 a 1k o $0.5294 a 2k) è il punto d'equilibrio pratico per la maggior parte delle schede Shopify, Amazon A+ e store cross-border: offre abbastanza spazio verticale per un visual hero, dettagli macro dei materiali, scene d'uso, tabella dimensioni e contenuto della confezione senza diluire il racconto.
Riserva long (~11–18 sezioni, $0.7563 a 1k o $0.8319 a 2k) a elettronica di punta, elettrodomestici o kit multi-variante che richiedono davvero fasce narrative, esplosi dei componenti, guide d'uso passo passo, certificazioni e blocchi FAQ. Quando non disponi di abbastanza fatti distinti sul prodotto per riempire undici o più sezioni, la modalità long tende a ripetere angolazioni precedenti o a inventare banner lifestyle generici, sprecando sia tempo di render sia budget.
Perché la modalità webpage separa i riferimenti di stile e soggetto
In modalità webpage, separare style_refer_image da subject_refer_image evita un difetto classico delle API con un unico contenitore di riferimenti: il modello che copia il prodotto di un altro brand nel tuo layout oppure trasferisce lo sfondo disordinato della tua foto prodotto nell'interfaccia del sito. Passare uno screenshot editoriale o un frame Figma come style_refer_image lo limita a ritmo di griglia, token colore, gerarchia tipografica e stile dei pulsanti, mentre uno scatto pulito in studio come subject_refer_image mantiene fedele l'oggetto fisico nell'hero e nelle card funzionalità. Se vuoi una direzione artistica originale dal solo testo, ometti entrambi i campi immagine e descrivi palette, abbinamento font e griglia direttamente nel prompt.
Controllo qualità prima di pubblicare le pagine generate
Anche a risoluzione 2k, le immagini lunghe generate devono superare un rapido controllo QA automatico e visivo prima di andare online su uno store o in una presentazione cliente. Primo: verifica ogni numero, unità di misura e riga di ingredienti rispetto al prompt originale — piccoli refusi tipografici nelle tabelle dense si notano molto più facilmente allo zoom 100% che in un'anteprima ridotta. Secondo: controlla che la geometria fisica del prodotto (posizione dei pulsanti, loghi, porte e proporzioni) resti coerente dalla fascia hero fino ai dettagli ravvicinati. Terzo: verifica la leggibilità verticale su un viewport mobile da 390 px dopo il taglio in sezioni: una riga desktop a 4 colonne nitida a 2.048 px di larghezza può diventare illeggibile su smartphone, a meno di richiedere nel prompt card mobile impilate o a 2 colonne ad alto contrasto.
Esempi completi di richiesta per entrambe le skill
1. Pagina dettaglio prodotto ecommerce (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 visivo webpage con riferimenti stile + soggetto (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)Note di ingegneria in produzione: timeout, PNG oltre 50 MB e slicing
Integrare kling-image-4-0-long-image in un servizio backend differisce dall'integrazione di un generatore rapido 1024×1024 sotto tre aspetti operativi:
- Metti in conto latenze di diversi minuti. Un render ecommerce
long+2krichiede abitualmente alcuni minuti. Non tenere aperta una richiesta HTTP da un browser o da una funzione serverless con timeout di 30 secondi; accoda l'ID attività in un worker in background ed esegui il polling diGET /v1/tasks/:idcon un tetto di 10 minuti. - Scarica in streaming i PNG voluminosi. Poiché un'immagine lunga
2kè larga 2.048 pixel e può estendersi in verticale per 10.000–20.000+ pixel, i file PNG finiti possono superare 50 MB. Usa download in streaming (requests.get(url, stream=True)) con timeout di lettura generosi ed evita di mantenere in memoria più bitmap grezze dentro container piccoli. - Taglia e ricodifica per gli store live. Le piattaforme marketplace (Shopify, Amazon A+, Taobao/Tmall) e i browser mobile penalizzano singoli PNG da 50 MB. Dopo aver verificato il layout generato, ritaglia il PNG master lungo i confini delle sezioni e converti ogni sezione in WebP o JPEG progressivo all'80–85% di qualità per un caricamento rapido.
Errori HTTP 400 comuni da prevenire
Convalida queste cinque condizioni prima di chiamare l'endpoint:
settings.skillmancante (deve essere"ecommerce"o"webpage").skill: "ecommerce"con zero elementirefer_imageo più di tre.- Passaggio di
refer_imagein modalitàwebpage, oppure distyle_refer_image/subject_refer_imagein modalitàecommerce. - Richiesta di
resolution: "4k"(per Long Image esistono solo"1k"e"2k"). - Riutilizzo della stessa stringa
idsu due elementi di riferimento incontents.
Se il tuo flusso richiede scatti di campagna orizzontali o quadrati standard, set lifestyle di prodotto o fino a 10 immagini di riferimento in un solo fotogramma, instrada quei job su Kling Image 4.0 e riserva Kling Image 4.0 Long Image alle composizioni di pagina verticali multi-fascia.
Fonti
- Pagina modello TokLab Kling Image 4.0 Long Image — Playground interattivo, tabella delle fasce 1K/2K dal vivo e calcolatore.
- Riferimento API TokLab Kling Image 4.0 Long Image — Schema ufficiale, limiti di caratteri e vincoli di validazione.
- API prezzi dal vivo TokLab — Feed tariffario leggibile da macchina verificato il 20 novembre 2026.


