# Kling Image 4.0 — /images/generations

Kling Image 4.0 de Kuaishou (Beta): texto a imagen e imagen a imagen con hasta 10 referencias, 2K / 4K en 8 proporciones, entregado como PNG original con su credencial de contenido C2PA. Sus puntos fuertes: textura realista y texto dentro de la imagen, chino incluido.

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

## Inicio rápido

Tres pasos: envía un trabajo, consúltalo y toma el enlace de la imagen. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual.

**Paso 1 · Envía el trabajo (devuelve al momento un id de trabajo, HTTP 202)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0", "prompt": "Cartel de rebajas del Medio Otoño, titular grande “Luna llena, familia unida” en el centro, debajo “20% en todo”, tonos dorados cálidos, luna llena y osmanto", "size": "16:9", "resolution": "2K"}'
```

Respuesta (HTTP 202)

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

**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",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "kling-image-4.0"}
}
```

**Paso 3: descarga data[0].url, el PNG original de Kling (con su credencial de contenido C2PA); 4K pesa unos 30 MB y se guarda 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"}

# 1. enviar el trabajo
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "kling-image-4.0",
    "prompt": "Cartel de rebajas del Medio Otoño, titular grande “Luna llena, familia unida” en el centro, debajo “20% en todo”, tonos dorados cálidos, luna llena y osmanto",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. consultar cada 3 segundos hasta que termine
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. descargar la imagen
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("kling-image-4.0.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`. |
| prompt | string | Sí | Qué dibujar. En imagen a imagen, indica qué cambiar. |
| size | string | No | Proporción: `1:1` (por defecto), `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`. Un tamaño en píxeles (p. ej. `2720x1536`) se ajusta por su proporción a una de estas 8; cualquier otra devuelve 400 al enviar y no se cobra. |
| resolution | string | No | Nivel: `2K` (por defecto) o `4K`; no hay 1K ni 8K (1K devuelve 400 al enviar y no se cobra). |
| image / images | string / array | No | Referencias: una en image, varias en images, hasta 10, como URL de imagen, data: URI o base64; jpg / png, al menos 300 px por lado, proporción entre 2:5 y 5:2. Nómbralas en orden como @image1, @image2 en el prompt y di para qué sirve cada una. Cada imagen de referencia cuesta $0.003 más. |
| n | integer | No | Una imagen por solicitud: n debe ser 1. Envía varios trabajos para varias imágenes. |
| callback_url | string | No | Adónde enviar el resultado cuando termine el trabajo; consulta la sección de webhooks más abajo. |

Los demás parámetros de OpenAI (quality, style, background, response_format, etc.) no tienen efecto. Cada solicitud genera un PNG original; cada imagen de referencia cuesta $0.003 más y se reserva junto con la imagen al enviar.

## Precio

Se cobra por imagen, solo según el nivel: la proporción y que sea texto a imagen o imagen a imagen no cambian nada. El precio del nivel se retiene al enviar y se reembolsa íntegro si el trabajo falla. 1 crédito = $0.005.

| Nivel | Créditos por imagen | USD por imagen |
| --- | --- | --- |
| 2K | 12 | $0.06 |
| 4K | 18 | $0.09 |

## Proporción, resolución y tamaño de salida

Cada proporción y nivel tiene un tamaño nativo fijo (medido el 11-20); recibes el original, sin recortes ni redimensionado. 4K es el doble de 2K por lado.

| Proporción | 2K | 4K |
| --- | --- | --- |
| 1:1 | 2048x2048 | 4096x4096 |
| 16:9 | 2720x1536 | 5440x3072 |
| 9:16 | 1536x2720 | 3072x5440 |
| 4:3 | 2336x1760 | 4672x3520 |
| 3:4 | 1760x2336 | 3520x4672 |
| 3:2 | 2496x1664 | 4992x3328 |
| 2:3 | 1664x2496 | 3328x4992 |
| 21:9 | 3136x1326 | 6272x2651 |

- Solo estas 8 proporciones; cualquier otra (9:21, 1:2, etc.) devuelve 400 al enviar y no se cobra.

- size también admite píxeles (p. ej. `5440x3072`): se ajusta a la tabla por proporción, y un lado mayor de más de 3200 px significa 4K, si no 2K; si envías resolution, manda resolution.

## Imagen a imagen e imágenes de referencia

- Envía `image` (una imagen) o `images` (varias, hasta 8; las que pasen de 8 no se usan) y el trabajo será de imagen a imagen; indica en el prompt qué cambiar. `POST /v1/images/edits` acepta los mismos parámetros.

- Los dos endpoints solo aceptan un cuerpo JSON, no la subida de archivos multipart, así que `images.edit()` del SDK de OpenAI no se puede usar tal cual: pasa enlaces o base64 como en el ejemplo de abajo.

- Cada referencia puede ser una URL pública de imagen (http o https), un data: URI o base64 puro, de hasta 16MB cada una, en un formato habitual como JPEG, PNG o WebP.

- La URL tiene que descargar directamente la imagen: no puede ser una página web ni estar detrás de un inicio de sesión o de una protección contra hotlinking. Una referencia que no podemos leer se rechaza al enviar con un 400 que indica cuál es y por qué; no se crea ningún trabajo y no se cobra nada.

- Hasta 10 referencias (jpg / png, al menos 300 px por lado, proporción 2:5-5:2); nómbralas en orden como @image1, @image2 y di para qué sirve cada una; las que no menciones también cuentan. Cada imagen de referencia cuesta $0.003 más.

- Alojamos las referencias por ti y las guardamos 7 días.

**Imagen a imagen con dos referencias**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0", "prompt": "Mantén a las personas y cambia el fondo por una playa de noche con guirnaldas de luces cálidas", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'
```

## 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: 2K en 33-52 s, 4K en 57-74 s, 2K con dos referencias unos 70 s; 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 | 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", "prompt": "Cartel de rebajas del Medio Otoño, titular grande “Luna llena, familia unida” en el centro, debajo “20% en todo”, tonos dorados cálidos, luna llena y osmanto", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```
