KovAPIKovAPI
kling-image-4.0-long

Kling Image 4.0 Long · API

POST https://kovapi.com/v1/images/generations

El modo de imagen larga de Kling Image 4.0 de Kuaishou (Beta): una página de producto o un diseño web completo en una sola imagen alta. 1K / 2K, entregado como PNG original con su credencial de contenido C2PA, cobrado por tipo de página, longitud y resolución.

Probar en el Playground →

Inicio rápido

Un trabajo asíncrono como las demás llamadas de imagen: envías, recibes un id de trabajo y consultas el resultado. Una página de producto necesita 1-3 fotos; una web puede ser solo texto.

Paso 1: envía una página de producto (skill, length, resolution y las fotos del producto)

curl
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "Página de producto para el termo de la imagen 1: imagen principal, tres puntos de venta, escena de uso, textos en español; usa solo lo que se ve en la foto, sin inventar especificaciones", "skill": "ecommerce", "length": "medium", "resolution": "1K", "images": ["https://example.com/mug.jpg"]}'

Respuesta (HTTP 202)

JSON
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "kling-image-4.0-long"
}

Paso 2 · Consulta cada 2–3 segundos hasta que status sea succeeded o failed

curl
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

Respuesta cuando sale bien

JSON
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "kling-image-4.0-long",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "kling-image-4.0-long"}
}

Paso 3: descarga data[0].url, el PNG largo original de Kling (1024 / 2048 px de ancho, la altura depende del contenido), guardado 7 días.

Ejemplo completo (Python: enviar, esperar y guardar en disco)

Python
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Una web: las imágenes son opcionales
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "kling-image-4.0-long",
    "prompt": "Página de inicio para Northbound Coffee, un tostador de especialidad: imagen principal y titular, tres cafés insignia, historia de la marca, pie de página, textos en español, estilo cálido y minimalista",
    "skill": "webpage",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

while job["status"] not in ("succeeded", "failed"):
    time.sleep(5)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("kling-image-4.0-long.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

Autenticación

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Crea una clave API en la consola para empezar.

Parámetros de la petición

El cuerpo JSON de POST /v1/images/generations:

ParámetroTipoObligatorioDescripción
modelstringSíEl ID del modelo: kling-image-4.0-long.
promptstringSíQué dibujar. En imagen a imagen, indica qué cambiar.
skillstringNoTipo de página: ecommerce (página de producto; 1-3 fotos en images) o webpage (diseño web). Si se omite: ecommerce con imágenes, webpage sin ellas.
lengthstringNoLongitud de la página de producto: short (unas 2-5 secciones), medium (por defecto, unas 6-10), long (unas 11-18); omítelo para una web.
resolutionstringNo1K (por defecto, 1024 px de ancho) o 2K (2048 px de ancho); no hay 4K.
image / imagesstring / arrayNoPágina de producto: 1-3 fotos del producto (obligatorio). Web: hasta 2; por defecto la primera es la referencia de sujeto y la segunda la de estilo. jpg / png, al menos 300 px por lado, proporción 2:5-5:2; cada una cuesta $0.003 más.
image_rolesarrayNoSolo web: uno por imagen de images, subject o style, como máximo uno de cada, p. ej. ["style", "subject"].
nintegerNoUna imagen larga por solicitud: n debe ser 1.
callback_urlstringNoAdónde enviar el resultado cuando termine el trabajo; consulta la sección de webhooks más abajo.

Precio

Se cobra por imagen según tipo de página, longitud y resolución; cada imagen de referencia cuesta $0.003 más. Se reserva al enviar y se libera por completo si falla.

Tipo1K · Créditos por imagen1K · USD por imagen2K · Créditos por imagen2K · USD por imagen
Página de producto · corta47$0.23556$0.28
Página de producto · media94$0.47109$0.545
Página de producto · larga156$0.78172$0.86
Web109$0.545119$0.595

Tamaño y formato

  • Ancho fijo: 1024 px en 1K, 2048 px en 2K; la altura depende del contenido (4.257-16.270 px medidos el 11-20).
  • El PNG original con su credencial de contenido C2PA, sin recortes ni redimensionado; una imagen larga 2K puede pesar decenas de MB.
  • Una imagen larga completa por solicitud; no devuelve HTML ni archivos de diseño editables.

Cómo escribir el prompt

  • Indica el propósito, el idioma, el orden de secciones, los puntos de venta y los textos. Escribe el prompt en el idioma de los textos y pídelo expresamente, p. ej. «textos en español».
  • Da solo datos reales del producto y añade «usa solo los datos proporcionados; no inventes especificaciones»: el modelo escribe lo que le das y puede añadir detalles propios.
  • Nombra las imágenes como @image1, @image2 en el prompt.

Estado y campos del trabajo

GET /v1/images/jobs/{id} devuelve estos estados; cada campo se describe en Trabajos asíncronos. Consulta cada 2–3 segundos o usa un webhook.

EstadoSignificado
queuedEn cola. Incluye queue_position (trabajos por delante del tuyo) y eta_seconds (espera estimada).
processingGenerándose.
succeededTerminado. El resultado está en data[0].url y el detalle del cobro en usage.
failedFalló. El motivo está en error; los créditos reservados se devuelven íntegros.

Cada cuenta ejecuta hasta 50 trabajos a la vez; los demás esperan en orden de envío, y un trabajo que no ha empezado a los 15 minutos falla y se reembolsa íntegro. Los registros de trabajos se guardan 3 días y los enlaces de las imágenes, 7 días.

Cuánto tarda

Medido el 11-20: unos 1,5-2,5 minutos en 1K y 2,5 en 2K; las páginas largas tardan más y en horas punta puede tardar más.

Errores y reembolsos

Un error al enviar se devuelve al momento como HTTP 4xx / 5xx: no se crea ningún trabajo y no se cobra nada. Un fallo después de que el trabajo fue aceptado lo informa el endpoint del trabajo, y la retención se reembolsa íntegra. Todos los códigos están en Códigos de error.

Errores al enviar

HTTPcodeCausaQué hacer
400missing_promptLa petición a /v1/images/generations no lleva prompt.Añade un prompt.
400invalid_requestNo se puede leer una imagen de referencia (enlace roto, no es una imagen, supera 16MB...; message indica cuál y por qué), /v1/images/edits no lleva imagen de referencia, el cuerpo no es un objeto JSON o n no es un entero.Corrige lo que indica message y vuelve a enviar la petición.
400unsupported_resolutionEl modelo no ofrece el nivel de resolución elegido (por ejemplo, la generación de imágenes de Grok no tiene 4K).Elige otro nivel; la documentación de cada modelo indica sus niveles.
400model_not_foundEl ID del modelo está mal escrito, falta model, o el modelo no se puede usar en este endpoint (por ejemplo, un modelo de chat en el endpoint de imágenes).Usa un ID de modelo de GET /v1/models o de la referencia de la API.
401invalid_api_keyLa clave no existe, se eliminó o está desactivada, o la cuenta está desactivada.Revisa la clave en la página API Keys de la consola.
402insufficient_quotaNo hay saldo suficiente para retener el importe de esta petición. La pasarela retiene primero el coste máximo posible de la petición, así que una ráfaga de llamadas simultáneas también puede provocarlo.Si se debe a una ráfaga, espera unos segundos y reintenta; si no, recarga.
429rate_limit_exceededSe superó el límite de peticiones por minuto configurado en esta clave (contado sobre los últimos 60 segundos). Sin cabecera Retry-After.Espera unos segundos y reintenta, o sube el límite de la clave en la consola.
503model_maintenanceEl modelo está en mantenimiento y no acepta peticiones; mientras tanto, ningún otro modelo responde en su lugar.Reintenta cuando termine el mantenimiento; consulta el estado del servicio.
503service_unavailableUn fallo temporal de nuestro lado, por ejemplo al guardar un archivo de referencia; /v1/responses también responde 503, con Retry-After, cuando no puede atender peticiones por un momento.Reintenta en breve.

Trabajos fallidos (status failed)

codeCuándo apareceQué hacer
moderation_blockedImagen: el sistema de seguridad del proveedor del modelo rechazó el prompt o una imagen de referencia (el código también puede ser content_policy_violation).Reescribe el prompt o cambia la referencia; si se reenvía sin cambios, normalmente se vuelve a rechazar.
upstream_errorCualquier otro fallo: los reintentos automáticos no bastaron, el trabajo esperó 15 minutos sin empezar, el proveedor lo rechazó sin dar motivo, etc.; message indica cuál.Volver a enviarlo suele funcionar.

Webhooks en lugar de consultas

Añade callback_url al enviar y, en cuanto termine el trabajo, con éxito o con error, la pasarela enviará a esa URL exactamente lo mismo que devuelve el endpoint de consulta, firmado y con reintentos si la entrega falla. También puedes configurar una dirección para toda la cuenta en Configuración → Webhook, en la consola. Documentación de webhooks →

curl · callback_url
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "Página de inicio para Northbound Coffee, un tostador de especialidad: imagen principal y titular, tres cafés insignia, historia de la marca, pie de página, textos en español, estilo cálido y minimalista", "skill": "webpage", "callback_url": "https://your-domain.com/webhook"}'