API de Kling Image 4.0 Long Image para e-commerce y páginas web
Genera fichas e-commerce y páginas web 1K o 2K con la API de Kling Image 4.0 Long Image. Incluye modos duales, niveles de precio, validación y timeouts.
Leer en MarkdownLas APIs de imagen estándar fallan en cuanto pides una ficha de producto e-commerce vertical completa o una maqueta de landing page con varias secciones. Las proporciones se quedan en torno a 9:16 o 21:9, la tipografía cambia entre bloques sueltos y unir banners a mano deja cortes visibles. Kling Image 4.0 Long Image (kling-image-4-0-long-image) resuelve justo ese flujo renderizando todo el diseño vertical en un único PNG largo coherente con una sola llamada POST /v1/images/generations.
A diferencia de Kling Image 4.0, que genera imágenes independientes en 2K o 4K y series de varios planos, el endpoint Long Image gira en torno a dos modos especializados —ecommerce y webpage—, cada uno con sus propios tipos de imágenes de referencia, controles de longitud y niveles de precio. A finales de noviembre de 2026, la mayoría de los resultados de búsqueda todavía confunden este modelo con Kling de vídeo o con escaladores genéricos. Esta guía reúne el contrato API verificado, todos los niveles de tarifa, las reglas de validación reales y los detalles de ingeniería necesarios para gestionar renders de varios minutos y descargas PNG de más de 50 MB sin fallos.
Dos modos, dos contratos de entrada estrictos
Toda solicitud a kling-image-4-0-long-image debe declarar settings.skill como ecommerce o webpage. Mezclar tipos de referencia entre ambos modos devuelve un error de validación HTTP 400 antes de facturar.
| Campo / regla | skill: "ecommerce" | skill: "webpage" |
|---|---|---|
| Entregable principal | Ficha vertical de producto (PDP) | Diseño visual completo de página web |
| Tipos de referencia | refer_image (obligatorio: 1 a 3 fotos) | style_refer_image (0–1) y subject_refer_image (0–1) |
| Llamadas solo texto sin referencia | Rechazadas (HTTP 400) | Permitidas |
settings.length | short (~2–5 secciones), medium (predeterminado, ~6–10), long (~11–18) | Ignorado (omitir) |
settings.resolution | 1k (1024 px de ancho, predeterminado) o 2k (2048 px de ancho) | 1k (1024 px de ancho, predeterminado) o 2k (2048 px de ancho) |
Resolución 4k | No compatible (HTTP 400) | No compatible (HTTP 400) |
| Cantidad de salidas | Siempre 1 PNG largo (output.data[0].url) | Siempre 1 PNG largo (output.data[0].url) |
Cada URL de imagen de referencia debe ser un JPEG o PNG accesible públicamente por HTTP(S) de hasta 30 MB, con al menos 300 píxeles por lado y una relación ancho/alto entre 2:5 y 5:2. Ten en cuenta que las referencias element no son compatibles con kling-image-4-0-long-image.
La capacidad del prompt es inusualmente amplia frente a los generadores habituales: hasta 166 000 caracteres en inglés o 71 000 caracteres no ingleses (los prompts mixtos deben cumplir english / 166000 + non_english / 71000 <= 1). Ese margen existe para que puedas incluir el texto completo sección por sección, tablas técnicas verificadas, listas de ingredientes y rótulos en lugar de dejar que el modelo invente datos del producto.
Niveles de precio en vivo y cálculo de imágenes de referencia
Cada tarea completada de Long Image factura una tarifa fija por nivel —determinada por skill, resolution y (en ecommerce) length— más un cargo de imagen de referencia por cada foto de entrada desde la primera. Las solicitudes fallidas o inválidas no tienen coste.
Cuánto cuesta Kling Image 4.0 Long Image
| Categoría | Precios (USD) |
|---|---|
| Ecommerce · 1K · corta | $0.2269 |
| Ecommerce · 2K · corta | $0.2723 |
| Ecommerce · 1K · media | $0.4538 |
| Ecommerce · 2K · media | $0.5294 |
| Ecommerce · 1K · larga | $0.7563 |
| Ecommerce · 2K · larga | $0.8319 |
| Webpage · 1K | $0.5294 |
| Webpage · 2K | $0.5748 |
| Imagen de referencia | $0.003025 |
En https://api.toklab.ai/v1/pricing (verificado el 20 de noviembre de 2026), los ocho niveles de salida se desglosan así, sumando $0.003025 por cada imagen de referencia de entrada:
| Modo | Longitud | Resolución | Tarifa de salida | Ejemplo con 2 referencias |
|---|---|---|---|---|
ecommerce | short (~2–5 secciones) | 1k | $0.2269 | $0.23295 |
ecommerce | short (~2–5 secciones) | 2k | $0.2723 | $0.27835 |
ecommerce | medium (~6–10 secciones) | 1k | $0.4538 | $0.45985 |
ecommerce | medium (~6–10 secciones) | 2k | $0.5294 | $0.53545 |
ecommerce | long (~11–18 secciones) | 1k | $0.7563 | $0.76235 |
ecommerce | long (~11–18 secciones) | 2k | $0.8319 | $0.83795 |
webpage | n/a | 1k | $0.5294 | $0.53545 |
webpage | n/a | 2k | $0.5748 | $0.58085 |
Fíjate bien en el salto de 1K a 2K: subir de 1k a 2k solo añade $0.0454 en webpage (+8,6 %) y $0.0756 en ecommerce medium o long (+10 % a +16,7 %). Como las páginas largas concentran etiquetas pequeñas de interfaz, tablas de especificaciones y texto de cuerpo, 2k (2048 px de ancho) casi siempre compensa ese pequeño extra para los entregables finales, mientras que 1k resulta ideal para borradores estructurales baratos antes de cerrar el esquema.

Cómo estructurar prompts para ecommerce frente a webpage
Como el modelo compone toda la página vertical de una sola vez, los prompts vagos producen secciones de relleno repetitivas o especificaciones inventadas. Tratar el prompt como una especificación de wireframe ofrece diseños mucho más limpios:
- Enumera las secciones en orden exacto de arriba abajo. Numera cada bloque explícitamente; por ejemplo:
Sección 1: Banner principal,Sección 2: 3 columnas de ventajas,Sección 3: Detalle macro de textura,Sección 4: Tabla de especificaciones,Sección 5: Instrucciones de cuidado y pie. - Ancla cada foto de referencia con
@id. En modoecommerce, asigna IDs claros (front,spout,box) e indica qué bloque debe mostrar cada ángulo. En modowebpage, separa el estilo visual (@layoutmediantestyle_refer_image) del objeto protagonista (@productmediantesubject_refer_image). - Aporta textos y cifras exactas. Nunca escribas «añade especificaciones técnicas realistas». Indica la potencia, dimensiones, materiales y titulares exactos que quieres renderizar para no tener que retocar datos inventados después.
- Ajusta
settings.lengtha tu número de secciones. Pedir 14 bloques detallados dentro delength: "short"comprime la tipografía hasta volver borrosas las etiquetas pequeñas. Empareja 2–5 bloques conshort, 6–10 conmediumy 11–18 conlong.
Elegir el nivel de longitud adecuado en ecommerce
Elegir entre short, medium y long es tanto una decisión de ritmo visual como una palanca de presupuesto. Una página short (~2–5 secciones, $0.2269 en 1k o $0.2723 en 2k) encaja en tarjetas promocionales de un solo SKU, adelantos móviles para marketplaces y tiras comparativas donde el comprador solo necesita una foto principal, tres argumentos y un bloque técnico compacto. Una página medium (~6–10 secciones, $0.4538 en 1k o $0.5294 en 2k) es el punto óptimo práctico para la mayoría de tiendas Shopify, Amazon A+ y escaparates internacionales: da suficiente espacio vertical para una cabecera, planos detalle de materiales, escenas de uso, tabla de dimensiones y contenido de la caja sin estirar artificialmente el relato.
Reserva long (~11–18 secciones, $0.7563 en 1k o $0.8319 en 2k) para electrónica insignia, electrodomésticos o kits multivariante que de verdad necesiten bandas narrativas, diagramas despiezados, guías paso a paso, sellos de certificación y bloques de preguntas frecuentes. Cuando no tienes suficientes datos distintos para llenar once o más secciones, el modo long tiende a repetir ángulos anteriores o inventar banners genéricos, desperdiciando tiempo de renderizado y presupuesto.
Por qué el modo webpage separa referencias de estilo y de sujeto
En modo webpage, separar style_refer_image de subject_refer_image evita un fallo clásico de las APIs con una sola bolsa de referencias: que el modelo copie el producto de otra marca dentro de tu diseño o traslade el fondo recargado de tu foto de producto a la interfaz de la web. Pasar una captura editorial o un marco de Figma como style_refer_image lo limita al ritmo de retícula, paleta de color, jerarquía tipográfica y estilo de botones, mientras que pasar una foto limpia de estudio como subject_refer_image mantiene fiel el objeto físico desde la cabecera hasta las tarjetas de producto. Si buscas una dirección de arte original solo con texto, omite ambos campos de imagen y describe la paleta, las fuentes y la retícula directamente en el prompt.
Control de calidad antes de publicar páginas generadas
Incluso en resolución 2k, las imágenes largas generadas deben pasar una breve revisión automática y visual antes de salir a tienda o a una presentación. Primero, comprueba cada cifra, unidad y línea de ingredientes frente al prompt original: los pequeños fallos tipográficos en tablas densas se detectan mucho mejor al 100 % de zoom que en una vista reducida. Segundo, verifica que la geometría física del producto (posición de botones, logotipos, puertos y proporciones) se mantenga constante desde la cabecera hasta los primeros planos. Tercero, revisa la legibilidad vertical en un ancho móvil de 390 px tras el recorte: una fila de 4 columnas pensada para escritorio que se ve nítida a 2048 px puede volverse ilegible en un teléfono si no pides tarjetas de 2 columnas o apiladas de alto contraste.
Ejemplos completos de solicitud para ambos modos
1. Ficha de producto 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. Diseño visual de página web con referencias de estilo + sujeto (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)Notas de ingeniería en producción: timeouts, PNG de >50 MB y recorte
Integrar kling-image-4-0-long-image en un backend difiere de integrar un generador rápido de 1024×1024 en tres aspectos operativos:
- Planifica latencias de varios minutos. Un render e-commerce
long+2ksuele tardar varios minutos. No mantengas una petición HTTP abierta desde un navegador o función serverless con un timeout de 30 segundos; encola el ID de tarea en un worker en segundo plano y consultaGET /v1/tasks/:idcon un techo de 10 minutos. - Descarga en streaming los PNG grandes. Como una imagen larga
2kmide 2048 píxeles de ancho y puede alcanzar entre 10 000 y más de 20 000 píxeles de alto, los PNG finales pueden superar los 50 MB. Usa descargas en streaming (requests.get(url, stream=True)) con timeouts de lectura amplios y evita almacenar varios mapas de bits en memoria dentro de un contenedor pequeño. - Recorta y recodifica para tiendas en producción. Plataformas como Shopify, Amazon A+ o Taobao/Tmall y los navegadores móviles penalizan un único PNG de 50 MB. Tras verificar el diseño, divide el PNG maestro por los límites de sección y convierte cada franja a WebP o JPEG progresivo al 80–85 % de calidad para una carga rápida.
Errores HTTP 400 frecuentes que conviene evitar
Valida estas cinco condiciones antes de llamar al endpoint:
- Falta
settings.skill(debe ser"ecommerce"o"webpage"). skill: "ecommerce"con cero elementosrefer_imageo más de tres.- Enviar
refer_imageen modowebpage, ostyle_refer_image/subject_refer_imageen modoecommerce. - Solicitar
resolution: "4k"(solo existen"1k"y"2k"en Long Image). - Reutilizar el mismo
iden dos elementos de referencia dentro decontents.
Si tu flujo necesita fotos de campaña horizontales o cuadradas, series lifestyle de producto o hasta 10 imágenes de referencia en un solo encuadre, dirige esas tareas a Kling Image 4.0 y reserva Kling Image 4.0 Long Image para composiciones verticales de varias secciones.
Fuentes
- Página del modelo TokLab Kling Image 4.0 Long Image — Playground interactivo, tabla de tarifas 1K/2K en vivo y calculadora.
- Referencia API TokLab Kling Image 4.0 Long Image — Esquema oficial, límites de caracteres y restricciones de validación.
- API de precios en vivo de TokLab — Fuente de tarifas legible por máquina comprobada el 20 de noviembre de 2026.


