> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generación de imágenes Kling V4 Image

> Genera imágenes desde texto o hasta 10 imágenes de referencia y series de 2–4 imágenes relacionadas. El modo estándar produce 1–9 imágenes PNG en 2K / 4K / 8K por solicitud.

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": true
}'
```

```python Python theme={null}
import requests

payload = {
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": True
}
response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": true
};
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example_kling_v4_image"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "`prompt` is required for kling-v4-image",
    "type": "invalid_request_error"
  }
}
```

Envía una solicitud asíncrona a `POST /v1/images/generations` con `model: "kling-v4-image"`. Obtén `data[0].task_id` y consulta el resultado con `GET /v1/tasks/{task_id}`.

## Autenticación

**Authorization** `string` *required*

Usa `Authorization: Bearer <token>`, donde `<token>` es tu clave API de APIMart.

## Parámetros de la solicitud

**model** `string` *required*

Debe ser `kling-v4-image`.

**nsfw\_check** `boolean` (default: false)

Indica si se debe moderar el contenido antes de enviar la tarea de imagen.

* `true`: revisar los prompts y las imágenes de entrada con `omni-moderation-latest`
* `false` u omitido: no enviar una solicitud de moderación, sin coste ni latencia de moderación adicionales (predeterminado)

**prompt** `string` *required*

Obligatorio para generar desde texto, desde imágenes y en serie. Describe tanto el contenido deseado como el que quieres evitar. El límite es de 50.000 caracteres para texto solo en inglés y 21.000 para texto solo en chino o idiomas similares; en textos mixtos se calcula proporcionalmente.

**image\_urls** `string[]`

Hasta 10 imágenes de referencia mediante URL directas accesibles públicamente. Para archivos locales, usa la [API de carga de imágenes](https://docs.apimart.ai/es/api-reference/uploads/images.md) y pasa la `url` devuelta.

Admite JPG / JPEG / PNG / GIF. Cada imagen debe ocupar como máximo 30 MB, medir al menos 300 px tanto de ancho como de alto y tener una relación de aspecto entre 2:5 y 5:2.

Las referencias se comprueban al enviar la solicitud. Una URL que devuelve HTTP 403 / 404 / 410, un lado inferior a 300 px, una proporción fuera de 2:5–5:2 o una imagen mayor de 30 MB devuelve HTTP 400 inmediatamente, sin crear una tarea ni cobrar la generación. Otros fallos de descarga, como un tiempo de espera del servidor de origen, se aceptan inicialmente; la tarea falla después y se reembolsan por completo los cargos de generación descontados por adelantado.

Usa `@Image1`, `@Image2`, etc. en el prompt para referirte al orden de las imágenes en el array. También se usan como referencia sin estos marcadores.

**n** `integer` (default: 1)

Cantidad de salidas en modo estándar: entero de 1 a 9, por defecto 1. En modo serie, puedes omitir `n` o establecerlo en `1`; `sequential_image_generation_options.max_images` determina la cantidad de salidas. Enviar `n > 1` en una serie devuelve HTTP 400.

**resolution** `string` (default: 2K)

Admite `2K` (por defecto), `4K` y `8K`, sin distinguir mayúsculas de minúsculas. La salida es PNG. Con `1:1`, 2K equivale a `2048×2048`, 4K a `4096×4096` y 8K a `8192×8192`. Para otras proporciones, consulta las dimensiones reales de las imágenes devueltas.

8K también admite generación desde texto, desde imágenes y en serie: 1–9 resultados en modo estándar, 2–4 en serie y hasta 10 imágenes de referencia. Los formatos, dimensiones y el límite de 30 MB por imagen de referencia no cambian.

**size** `string` (default: auto)

Relación de aspecto de salida. Admite `auto` (por defecto) y estas 8 proporciones:

`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`.

`auto` elige la proporción según el prompt o las referencias. No se admiten dimensiones en píxeles como `2048x2048`.

**aspect\_ratio** `string`

Alias de `size` con los mismos valores. Si se proporcionan ambos, `aspect_ratio` tiene prioridad.

**sequential\_image\_generation** `string` (default: disabled)

`disabled` o la omisión del campo activa la generación estándar. `auto` genera una serie de imágenes relacionadas y exige `sequential_image_generation_options.max_images`. Aquí, `auto` no elige automáticamente la cantidad de imágenes.

**sequential\_image\_generation\_options** `object`

Define la cantidad de imágenes en modo serie.

**Propiedades**

**max\_images** `integer`

Obligatorio en modo serie: entero de 2 a 4 que indica la cantidad de salida solicitada. Omitirlo, enviar la cadena `"auto"` o un valor fuera del rango devuelve HTTP 400.

> [!WARNING]
>
> No se admiten `width`, `height`, `mask_url`, `size` en píxeles ni `watermark: true`; enviarlos devuelve HTTP 400.

## Ejemplos de solicitud

Envía estas solicitudes a `POST /v1/images/generations`. Sustituye las URL de ejemplo por enlaces directos accesibles.

### Generación desde una imagen

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "Use the dog in @Image1 as a reference for a 3D animated character poster, preserving its fur color and features",
  "image_urls": [
    "https://example.com/dog.png"
  ],
  "size": "3:4",
  "resolution": "2K"
}'
```

### Generar tres imágenes 4K

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "A quiet mountain lake at sunrise, detailed landscape photography",
  "size": "16:9",
  "resolution": "4K",
  "n": 3
}'
```

### Generar una imagen 8K

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "A sweeping aerial view of a misty mountain valley at sunrise",
  "resolution": "8K",
  "size": "16:9",
  "n": 1
}'
```

### Generar una serie de cuatro imágenes 8K relacionadas

Establece `max_images` entre 2 y 4. En serie, `n` se puede omitir o establecer en `1`, pero no puede superar `1`. Una serie puede tardar varios minutos; guarda el `task_id` y consulta su estado para evitar envíos duplicados.

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "The same tree in spring, summer, autumn, and winter, consistent picture-book style",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {
    "max_images": 4
  },
  "size": "3:4",
  "resolution": "8K"
}'
```

## Ejemplos de resultados 8K y tiempos

Las siguientes mediciones son muestras del entorno de pruebas. Las dimensiones, los tamaños de archivo y los tiempos son orientativos; los resultados reales pueden variar.

| Solicitud 8K | Dimensiones de salida | Tamaño de archivo por imagen | Tiempo hasta finalizar |
| - | - | - | - |
| 1 imagen en modo estándar (16:9) | `10880×6144` | 117 MB | Unos 2,5 minutos |
| 4 / 9 imágenes en modo estándar (1:1) | `8192×8192` | 100–130 MB | Unos 3 minutos |
| Serie de 4 imágenes (3:4) | `7040×9344` | 77–104 MB | Unos 6 minutos |

Consulta cada 5–10 segundos hasta `completed` o `failed`. `estimated_time` es fijo en 60 segundos y no debe usarse como estimación real ni como cuenta regresiva. Conserva el `task_id` y evita reenviar la solicitud mientras esperas.

Los resultados 8K son PNG originales, y un archivo puede superar los 100 MB. Para listas y vistas previas, usa miniaturas que generes o carga las imágenes bajo demanda. Ofrece la descarga del original e indica que el archivo es grande.

## Consultar la tarea

Consulta `data.status` mediante la [API de consulta de tareas](https://docs.apimart.ai/es/api-reference/tasks/status.md): `pending` / `processing` indica que está en curso, `completed` que terminó correctamente y `failed` que falló, con detalles en `data.error.message`.

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/task_example_kling_v4_image' \
  --header 'Authorization: Bearer <token>'
```

Este ejemplo muestra la estructura de un resultado correcto. Las URL están en `data.result.images[].url[]`; `url` es un array. Recorre todas las salidas y descárgalas cuanto antes.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_image",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-image.png"
          ]
        }
      ]
    }
  }
}
```

## Facturación

Se factura según la cantidad real de imágenes generadas y la resolución elegida. Las referencias se cobran por imagen por separado. Consulta la [página de precios](https://apimart.ai/pricing).

| Concepto | Clave de precio |
| - | - |
| Cada imagen de salida 2K | `kling-v4-image@2K` |
| Cada imagen de salida 4K | `kling-v4-image@4K` |
| Cada imagen de salida 8K | `kling-v4-image@8K` |
| Cada imagen de referencia de entrada | `kling-v4-image@input` |

* En modo estándar, `n=3` se factura como 3 salidas; en serie, se usa la cantidad realmente devuelta.
* Cada referencia se cuenta una vez por solicitud, sin multiplicarla por la cantidad de salidas. Generar 3 imágenes con 2 referencias supone 2 entradas y 3 salidas.
* Las tareas de generación fallidas no se cobran; los cargos de generación descontados por adelantado se reembolsan por completo.

## Errores comunes de parámetros

Estos errores devuelven HTTP 400 de forma síncrona al enviar la solicitud, sin crear una tarea ni cobrar la generación. Consulta `error.message` para errores de envío y `data.error.message` para fallos después de crear la tarea.

| Fragmento del error | Solución |
| - | - |
| `` `prompt` is required for kling-v4-image `` | Proporciona un prompt no vacío. |
| `` `n` must be an integer between 1 and 9 `` | Usa un entero de 1 a 9 para `n`. |
| `` `n` cannot be combined with sequential_image_generation=auto `` | En serie, omite `n` o establécelo en `1`; usa `max_images` para controlar la cantidad de salidas. |
| `` `sequential_image_generation_options.max_images` is required for kling-v4-image series mode `` | Proporciona `max_images` al activar la serie. |
| `` `sequential_image_generation_options.max_images` must be an integer between 2 and 4 `` | Usa un entero de 2 a 4, no `"auto"`. |
| `` `resolution` must be 2K, 4K or 8K for kling-v4-image `` | Usa `2K`, `4K` u `8K`; no se distingue entre mayúsculas y minúsculas. |
| `` `size` must be auto or one of 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 `` | Usa `auto` o una proporción admitida, no dimensiones en píxeles. |
| `kling-v4-image supports at most 10 reference images` | Proporciona como máximo 10 referencias. |
| `reference image is not accessible for kling-v4-image` | La URL de referencia devolvió 403 / 404 / 410. Comprueba que sea pública y válida, o vuelve a cargar la imagen. |
| `unsupported reference image dimensions for kling-v4-image` | El ancho y el alto deben ser de al menos 300 px y la proporción debe estar entre 2:5 y 5:2. Los errores de proporción usan el mismo prefijo. |
| `reference image too large for kling-v4-image` | Cada referencia debe ocupar como máximo 30 MB. Comprímela antes de volver a enviarla. |
| `` `n` must be an integer between 1 and 9 for kling-v4-image (got: "3") `` | Usa un entero JSON como `"n": 3`, no la cadena `"3"`. Los demás campos también deben usar el tipo declarado: cadena, array o booleano. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.