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 Markdown

Le 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 / regolaskill: "ecommerce"skill: "webpage"
Deliverable principalePagina dettaglio prodotto verticale (PDP)Design visivo di pagina web scorrevole
Tipi di elemento riferimentorefer_image (obbligatorio: da 1 a 3 foto)style_refer_image (0–1) e subject_refer_image (0–1)
Chiamate solo testo senza riferimentiRespinte (HTTP 400)Consentite
settings.lengthshort (~2–5 sezioni), medium (predefinito, ~6–10), long (~11–18)Ignorato (omettere)
settings.resolution1k (1024 px di larghezza, predefinito) o 2k (2048 px)1k (1024 px di larghezza, predefinito) o 2k (2048 px)
Risoluzione 4kNon supportata (HTTP 400)Non supportata (HTTP 400)
Numero di outputSempre 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

CategoriaPrezzi (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:

SkillLunghezzaRisoluzioneTariffa outputEsempio con 2 riferimenti
ecommerceshort (~2–5 sezioni)1k$0.2269$0.23295
ecommerceshort (~2–5 sezioni)2k$0.2723$0.27835
ecommercemedium (~6–10 sezioni)1k$0.4538$0.45985
ecommercemedium (~6–10 sezioni)2k$0.5294$0.53545
ecommercelong (~11–18 sezioni)1k$0.7563$0.76235
ecommercelong (~11–18 sezioni)2k$0.8319$0.83795
webpagen/d1k$0.5294$0.53545
webpagen/d2k$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.

Esempio di pagina prodotto ecommerce Kling Image 4.0 Long Image generato su TokLab

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:

  1. 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.
  2. 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 (@layout tramite style_refer_image) dall'oggetto principale (@product tramite subject_refer_image).
  3. 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.
  4. Allinea settings.length al numero di sezioni. Chiedere 14 fasce dettagliate dentro length: "short" comprime la tipografia fino a rendere sfocate le etichette piccole. Abbina 2–5 fasce a short, 6–10 a medium e 11–18 a long.

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 + 2k richiede 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 di GET /v1/tasks/:id con 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:

  1. settings.skill mancante (deve essere "ecommerce" o "webpage").
  2. skill: "ecommerce" con zero elementi refer_image o più di tre.
  3. Passaggio di refer_image in modalità webpage, oppure di style_refer_image / subject_refer_image in modalità ecommerce.
  4. Richiesta di resolution: "4k" (per Long Image esistono solo "1k" e "2k").
  5. Riutilizzo della stessa stringa id su due elementi di riferimento in contents.

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

Guide correlate