# Kling Image 4.0 Long — /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.

**Endpoint:** `POST https://kovapi.com/v1/images/generations`

## 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 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)

```
{
  "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 https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Respuesta cuando sale bien

```
{
  "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)**

```
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
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Parámetros de la petición

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

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| model | string | Sí | El ID del modelo: `kling-image-4.0-long`. |
| prompt | string | Sí | Qué dibujar. En imagen a imagen, indica qué cambiar. |
| skill | string | No | Tipo 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. |
| length | string | No | Longitud 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. |
| resolution | string | No | `1K` (por defecto, 1024 px de ancho) o `2K` (2048 px de ancho); no hay 4K. |
| image / images | string / array | No | Pá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_roles | array | No | Solo web: uno por imagen de images, `subject` o `style`, como máximo uno de cada, p. ej. `["style", "subject"]`. |
| n | integer | No | Una imagen larga por solicitud: n debe ser 1. |
| callback_url | string | No | Adó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.

| Tipo | 1K · Créditos por imagen | 1K · USD por imagen | 2K · Créditos por imagen | 2K · USD por imagen |
| --- | --- | --- | --- | --- |
| Página de producto · corta | 47 | $0.235 | 56 | $0.28 |
| Página de producto · media | 94 | $0.47 | 109 | $0.545 |
| Página de producto · larga | 156 | $0.78 | 172 | $0.86 |
| Web | 109 | $0.545 | 119 | $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](https://docs.kovapi.com/es/guide/async-jobs#fields). Consulta cada 2–3 segundos o usa un webhook.

| Estado | Significado |
| --- | --- |
| queued | En cola. Incluye `queue_position` (trabajos por delante del tuyo) y `eta_seconds` (espera estimada). |
| processing | Generándose. |
| succeeded | Terminado. El resultado está en `data[0].url` y el detalle del cobro en `usage`. |
| failed | Falló. 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](https://docs.kovapi.com/es/guide/errors).

### Errores al enviar

| HTTP | code | Causa | Qué hacer |
| --- | --- | --- | --- |
| 400 | missing_prompt | La petición a `/v1/images/generations` no lleva `prompt`. | Añade un `prompt`. |
| 400 | invalid_request | No 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. |
| 400 | unsupported_resolution | El 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. |
| 400 | model_not_found | El 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](https://docs.kovapi.com/es/api). |
| 401 | invalid_api_key | La 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. |
| 402 | insufficient_quota | No 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. |
| 429 | rate_limit_exceeded | Se 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. |
| 503 | model_maintenance | El 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](https://kovapi.com/es/status). |
| 503 | service_unavailable | Un 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`)

| code | Cuándo aparece | Qué hacer |
| --- | --- | --- |
| moderation_blocked | Imagen: 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_error | Cualquier 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 →](https://docs.kovapi.com/es/webhooks)

```
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"}'
```
