> ## 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 largas Kling V4 Long Image

> Crea fichas de producto o diseños de páginas web en 1K / 2K. Admite short / medium / long para comercio y referencias de producto, estilo y sujeto. Un PNG 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-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": true
}'
```

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

payload = {
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "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-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "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_long_image"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": "invalid_request_error",
    "message": "reference image is not accessible for kling-v4-long-image: image_urls[0] returned HTTP 404; make sure the URL is public and still valid",
    "param": "",
    "type": "invalid_request_error"
  }
}
```

Envía una solicitud asíncrona a `POST /v1/images/generations` con `model: "kling-v4-long-image"`. Obtén `data[0].task_id` y consulta `GET /v1/tasks/{task_id}`. Cada solicitud devuelve un PNG vertical; el modo web genera una imagen del diseño de la página.

## Elegir modo

| Modo | `skill` | Referencias | Longitud |
| - | - | - | - |
| Ficha de producto | `ecommerce` | `image_urls`: 1–3 imágenes de producto obligatorias | `short` / `medium` / `long` |
| Diseño web | `webpage` | `image_with_roles`: estilo y sujeto opcionales, como máximo una imagen de cada | Omitir `length` |

## Autenticación

**Authorization** `string` *required*

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

## Parámetros de solicitud

**model** `string` *required*

Debe ser `kling-v4-long-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 y no puede contener solo espacios. Hasta 166.000 caracteres en inglés y 71.000 en chino o idiomas similares; el texto mixto se calcula proporcionalmente. Describe distribución, secciones, textos, estilo y sujeto.

**skill** `string` *required*

Obligatorio: `ecommerce` para fichas de producto o `webpage` para diseños web, sin distinguir mayúsculas. Cada modo usa campos de referencia distintos.

**length** `string` (default: medium)

Solo para `skill: "ecommerce"`: `short`, `medium` (por defecto) o `long`, aproximadamente 2–5, 6–10 o 11–18 secciones. El contenido y la altura reales dependen del resultado. Omite este campo en modo web; enviarlo devuelve HTTP 400.

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

Admite `1K` (por defecto) y `2K`, sin distinguir mayúsculas, para todas las longitudes de comercio, incluido `long + 2K`. El ancho de salida es de 1024 o 2048 px respectivamente; la altura depende del contenido. No admite `4K`.

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

Solo para comercio: 1–3 imágenes de producto obligatorias. En modo web, omite este campo y usa `image_with_roles`. Usa URL directas públicas. 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.

**image\_with\_roles** `object[]`

Opcional, solo para web. Como máximo una imagen `style` y una `subject`; puedes omitir una o ambas. Omite este campo en modo comercio.

**Elemento del array**

**url** `string` *required*

URL directa y pública de la imagen de referencia.

**role** `string` *required*

`style` guía el estilo visual y la distribución; `subject` indica el sujeto que se debe conservar. Cada rol puede aparecer una sola vez.

**n** `integer`

Cada solicitud genera una imagen larga. Omite el campo o usa el entero `1`; otros valores devuelven HTTP 400.

**watermark** `boolean`

Omite el campo o usa `false`; `true` devuelve HTTP 400.

> [!WARNING]
>
> No envíes `size`, `aspect_ratio`, `width`, `height`, `mask_url`, `sequential_image_generation` ni `sequential_image_generation_options`. Incluso `null` o una cadena vacía en estos campos devuelve HTTP 400.

## Requisitos y referencias en el prompt

Admite JPG / JPEG / PNG. Máximo 30 MB por imagen, al menos 300 px por lado y proporción entre 2:5 y 5:2. Una URL con HTTP 403 / 404 / 410, dimensiones o proporciones inválidas o un archivo demasiado grande devuelve HTTP 400 síncrono, sin tarea ni cargo de generación. Otros fallos de descarga, como un tiempo de espera del servidor de origen, se aceptan inicialmente; después la tarea falla y se reembolsa el importe anticipado.

Usa `@Image1`, `@Image2`, etc. En comercio se sigue el orden de `image_urls`; en web, primero estilo y después sujeto. Si solo se proporciona una imagen, es `@Image1`.

## Ejemplos de solicitud

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

### Ficha de producto larga en 2K

```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-long-image",
  "skill": "ecommerce",
  "prompt": "Create a long product detail page using the front view in @Image1, side view in @Image2, and close-up in @Image3. Include key features, materials, use scenes, and care instructions.",
  "image_urls": [
    "https://example.com/product-front.jpg",
    "https://example.com/product-side.jpg",
    "https://example.com/product-detail.png"
  ],
  "length": "long",
  "resolution": "2K"
}'
```

### Web con referencias de estilo y sujeto

```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-long-image",
  "skill": "webpage",
  "prompt": "Design a product landing page using the visual style of @Image1 and preserving the product in @Image2. Include a hero section, features, and a call to action.",
  "image_with_roles": [
    {
      "url": "https://example.com/style.png",
      "role": "style"
    },
    {
      "url": "https://example.com/product.jpg",
      "role": "subject"
    }
  ],
  "resolution": "2K"
}'
```

### Web solo a partir del prompt

```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-long-image",
  "skill": "webpage",
  "prompt": "Design a welcoming coffee shop webpage with warm colors, a hero section, a menu, and store information",
  "resolution": "1K"
}'
```

## Consultar la tarea

Consulta la [API de tareas](https://docs.apimart.ai/es/api-reference/tasks/status.md) aproximadamente cada 10 segundos. Conserva el `task_id` y evita duplicar la solicitud de generación durante esperas largas.

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

| Estado (`data.status`) | Acción |
| - | - |
| `pending` / `processing` | Sigue consultando. `data.cost` es el cargo anticipado y `data.billing_status` es `held`. |
| `completed` | Lee `data.result.images[0].url[0]`. `data.billing_status` es `settled` y `data.cost` es el cargo final. |
| `failed` | Lee `data.error.message`. `data.billing_status` es `refunded`, `data.cost` es `0` y el cargo anticipado se devuelve íntegramente. |

Este ejemplo muestra la estructura de un resultado correcto. `images` y `url` son arrays; este modelo devuelve una imagen larga por solicitud.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_long_image",
    "status": "completed",
    "progress": 100,
    "billing_status": "settled",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-long-image.png"
          ],
          "expires_at": 1795331293
        }
      ]
    }
  }
}
```

Descarga la imagen antes de la marca de tiempo Unix en segundos de `data.result.images[0].expires_at`. El enlace caduca después.

> [!NOTE]
>
> La generación suele tardar varios minutos; una muestra `long + 2K` tardó 432 segundos. `estimated_time` devuelve actualmente 60 segundos fijos: no lo uses como cuenta atrás ni umbral de espera. La duración varía con el contenido y la carga; la muestra no es un límite.
>
> La altura y el tamaño del archivo varían según el contenido. Una muestra `long + 2K` tenía `2048×46615` y 63,9 MB; no son límites de salida. Los resultados pueden superar 50 MB, por lo que conviene considerar el coste de descarga y visualización de imágenes grandes.

## Facturación

Cada solicitud cobra una imagen larga al nivel de salida elegido, más las referencias: **precio del nivel de salida + cantidad de referencias × precio por referencia**. Producto, estilo y sujeto cuentan; la primera referencia también se cobra.

Hay 8 niveles de salida, indicados a continuación. Claves: `kling-v4-long-image@<nivel>` y `kling-v4-long-image@input` para referencias. En la solicitud de generación, `resolution` sigue aceptando solo `1K` o `2K`.

| Modo | Longitud | `1K` | `2K` |
| - | - | - | - |
| Ficha de producto | `short` | `1K-SHORT` | `2K-SHORT` |
| Ficha de producto | `medium` | `1K-MEDIUM` | `2K-MEDIUM` |
| Ficha de producto | `long` | `1K-LONG` | `2K-LONG` |
| Diseño web | Omitir `length` | `1K-WEBPAGE` | `2K-WEBPAGE` |

El importe se descuenta al enviar, se liquida al completar y se devuelve íntegramente si falla. Consulta la [página de precios](https://apimart.ai/pricing) para tarifas y descuentos de la cuenta.

## Errores comunes

Estos errores devuelven HTTP 400 síncrono, sin tarea ni cargo de generación. Lee `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-long-image `` | Proporciona un prompt no vacío. |
| `` `skill` is required for kling-v4-long-image `` | Proporciona `skill`. |
| `` `skill` must be ecommerce or webpage for kling-v4-long-image `` | Usa `ecommerce` o `webpage`. |
| `` skill=ecommerce on kling-v4-long-image requires 1 to 3 product images in `image_urls` `` | Comercio requiere 1–3 imágenes de producto. |
| `` skill=ecommerce on kling-v4-long-image supports at most 3 product images in `image_urls` `` | Como máximo 3 imágenes de producto. |
| `` `image_with_roles` is only for skill=webpage on kling-v4-long-image `` | En comercio, usa `image_urls` y omite `image_with_roles`. |
| `` `length` must be short, medium or long for kling-v4-long-image `` | Usa `short`, `medium` o `long`. |
| `` `length` only applies to skill=ecommerce for kling-v4-long-image `` | Omite `length` en modo web. |
| `` skill=webpage on kling-v4-long-image does not take `image_urls` `` | En web, omite `image_urls` y usa `image_with_roles`. |
| `` `image_with_roles[0].role` must be style or subject for kling-v4-long-image `` | Usa solo `style` o `subject`. |
| `kling-v4-long-image supports at most 1 image with role style` | Como máximo una imagen por rol; tampoco se permite duplicar sujeto. |
| `` `resolution` must be 1K or 2K for kling-v4-long-image `` | Usa `1K` o `2K`. |
| `` `size` is not supported by kling-v4-long-image `` | Elimina los campos no admitidos de tamaño, proporción o serie; no envíes `null` ni cadenas vacías. |
| `` `n` is not supported by kling-v4-long-image: each request returns one long image `` | Omite `n` o usa el entero `1`. |
| `reference image is not accessible for kling-v4-long-image` | Revisa acceso público, vigencia y respuestas 403 / 404 / 410. |
| `unsupported reference image dimensions for kling-v4-long-image` | Al menos 300 px por lado y proporción de 2:5 a 5:2. |
| `reference image too large for kling-v4-long-image` | Cada referencia debe ocupar como máximo 30 MB. |


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