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

# Geração de imagens longas Kling V4 Long Image

> Crie páginas de produto ou designs de páginas web em 1K / 2K. Suporta short / medium / long para comércio e referências de produto, estilo e sujeito. Um PNG por solicitação.

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

Envie uma solicitação assíncrona para `POST /v1/images/generations` com `model: "kling-v4-long-image"`. Obtenha `data[0].task_id` e consulte `GET /v1/tasks/{task_id}`. Cada solicitação retorna um PNG vertical; o modo web produz uma imagem do design da página.

## Escolher modo

| Modo | `skill` | Referências | Comprimento |
| - | - | - | - |
| Página de produto | `ecommerce` | `image_urls`: 1–3 imagens de produto obrigatórias | `short` / `medium` / `long` |
| Design de página web | `webpage` | `image_with_roles`: estilo e sujeito opcionais, no máximo uma imagem de cada | Omitir `length` |

## Autenticação

**Authorization** `string` *required*

Use `Authorization: Bearer <token>`, em que `<token>` é sua chave de API da APIMart.

## Parâmetros da solicitação

**model** `string` *required*

Deve ser `kling-v4-long-image`.

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

Define se o conteúdo deve ser moderado antes do envio da tarefa de imagem.

* `true`: verificar prompts e imagens de entrada com `omni-moderation-latest`
* `false` ou omitido: não enviar solicitação de moderação, sem custo nem latência adicionais de moderação (padrão)

**prompt** `string` *required*

Obrigatório, não pode conter apenas espaços. Até 166.000 caracteres em inglês e 71.000 em chinês ou idiomas semelhantes; textos mistos são calculados proporcionalmente. Descreva layout, seções, textos, estilo e sujeito.

**skill** `string` *required*

Obrigatório: `ecommerce` para páginas de produto ou `webpage` para design web, sem distinção de maiúsculas. Cada modo usa campos de referência diferentes.

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

Somente para `skill: "ecommerce"`: `short`, `medium` (padrão) ou `long`, aproximadamente 2–5, 6–10 ou 11–18 seções. Conteúdo e altura reais dependem do resultado. Omita este campo no modo web; enviá-lo retorna HTTP 400.

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

Aceita `1K` (padrão) e `2K`, sem distinção de maiúsculas, em todos os comprimentos comerciais, incluindo `long + 2K`. A largura de saída é 1024 ou 2048 px, respectivamente; a altura depende do conteúdo. `4K` não é suportado.

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

Somente para comércio: 1–3 imagens de produto obrigatórias. No modo web, omita o campo e use `image_with_roles`. Forneça URLs diretas públicas. Para arquivos locais, use a [API de upload de imagens](https://docs.apimart.ai/pt/api-reference/uploads/images.md) e envie a `url` retornada.

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

Opcional, somente para web. No máximo uma imagem `style` e uma `subject`; uma ou ambas podem ser omitidas. Omita o campo no modo comércio.

**Item do array**

**url** `string` *required*

URL direta e pública da imagem de referência.

**role** `string` *required*

`style` orienta o estilo visual e o layout; `subject` indica o sujeito a preservar. Cada função só pode aparecer uma vez.

**n** `integer`

Cada solicitação gera uma imagem longa. Omita o campo ou use o inteiro `1`; outros valores retornam HTTP 400.

**watermark** `boolean`

Omita o campo ou use `false`; `true` retorna HTTP 400.

> [!WARNING]
>
> Não envie `size`, `aspect_ratio`, `width`, `height`, `mask_url`, `sequential_image_generation` ou `sequential_image_generation_options`. Mesmo `null` ou string vazia nesses campos retorna HTTP 400.

## Requisitos e referências no prompt

Aceita JPG / JPEG / PNG. No máximo 30 MB por imagem, pelo menos 300 px em cada lado e proporção de 2:5 a 5:2. URL com HTTP 403 / 404 / 410, dimensões ou proporção inválidas e arquivo grande demais retornam HTTP 400 síncrono, sem tarefa ou cobrança de geração. Outras falhas de obtenção, como tempo limite do servidor de origem, são aceitas inicialmente; depois a tarefa falha e o valor antecipado é reembolsado.

Use `@Image1`, `@Image2` etc. No comércio, a ordem segue `image_urls`; no modo web, estilo primeiro e sujeito depois. Se houver apenas uma imagem, ela será `@Image1`.

## Exemplos de solicitação

Envie para `POST /v1/images/generations`. Substitua as URLs de exemplo por links diretos acessíveis.

### Página de produto longa em 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"
}'
```

### Página web com referências de estilo e sujeito

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

### Página web apenas com 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 a tarefa

Consulte a [API de tarefas](https://docs.apimart.ai/pt/api-reference/tasks/status.md) aproximadamente a cada 10 segundos. Guarde o `task_id` e evite duplicar a solicitação durante esperas longas.

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

| Status (`data.status`) | Ação |
| - | - |
| `pending` / `processing` | Continue consultando. `data.cost` é o valor antecipado e `data.billing_status` é `held`. |
| `completed` | Leia `data.result.images[0].url[0]`. `data.billing_status` é `settled` e `data.cost` é a cobrança final. |
| `failed` | Leia `data.error.message`. `data.billing_status` é `refunded`, `data.cost` é `0` e o valor antecipado é totalmente reembolsado. |

Este exemplo mostra a estrutura de um resultado bem-sucedido. `images` e `url` são arrays; este modelo retorna uma imagem longa por solicitação.

```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
        }
      ]
    }
  }
}
```

Baixe a imagem antes do timestamp Unix em segundos em `data.result.images[0].expires_at`. O link expira depois.

> [!NOTE]
>
> A geração costuma levar vários minutos; uma amostra `long + 2K` levou 432 segundos. `estimated_time` retorna atualmente 60 segundos fixos: não use como contagem regressiva ou limite de espera. O tempo varia com conteúdo e carga; a amostra não é um limite máximo.
>
> Altura e tamanho do arquivo variam com o conteúdo. Uma amostra `long + 2K` tinha `2048×46615` e 63,9 MB; esses valores não são limites de saída. Resultados podem ultrapassar 50 MB: considere o custo de download e exibição de imagens grandes.

## Cobrança

Cada solicitação cobra uma imagem longa na faixa escolhida, mais as referências: **preço da faixa de saída + quantidade de referências × preço por referência**. Produto, estilo e sujeito são contados; a primeira referência também é cobrada.

As 8 faixas de saída estão abaixo. Chaves: `kling-v4-long-image@<faixa>` e `kling-v4-long-image@input` para referências. Na solicitação de geração, `resolution` continua aceitando apenas `1K` ou `2K`.

| Modo | Comprimento | `1K` | `2K` |
| - | - | - | - |
| Página de produto | `short` | `1K-SHORT` | `2K-SHORT` |
| Página de produto | `medium` | `1K-MEDIUM` | `2K-MEDIUM` |
| Página de produto | `long` | `1K-LONG` | `2K-LONG` |
| Design de página web | Omitir `length` | `1K-WEBPAGE` | `2K-WEBPAGE` |

O valor é descontado no envio, liquidado no sucesso e totalmente reembolsado na falha. Consulte a [página de preços](https://apimart.ai/pricing) para tarifas e descontos da conta.

## Erros comuns

Estes erros retornam HTTP 400 síncrono, sem tarefa ou cobrança de geração. Leia `error.message` para erros de envio e `data.error.message` para falhas após criar a tarefa.

| Trecho do erro | Solução |
| - | - |
| `` `prompt` is required for kling-v4-long-image `` | Forneça um prompt não vazio. |
| `` `skill` is required for kling-v4-long-image `` | Forneça `skill`. |
| `` `skill` must be ecommerce or webpage for kling-v4-long-image `` | Use `ecommerce` ou `webpage`. |
| `` skill=ecommerce on kling-v4-long-image requires 1 to 3 product images in `image_urls` `` | Comércio exige 1–3 imagens de produto. |
| `` skill=ecommerce on kling-v4-long-image supports at most 3 product images in `image_urls` `` | No máximo 3 imagens de produto. |
| `` `image_with_roles` is only for skill=webpage on kling-v4-long-image `` | No comércio, use `image_urls` e omita `image_with_roles`. |
| `` `length` must be short, medium or long for kling-v4-long-image `` | Use `short`, `medium` ou `long`. |
| `` `length` only applies to skill=ecommerce for kling-v4-long-image `` | Omita `length` no modo web. |
| `` skill=webpage on kling-v4-long-image does not take `image_urls` `` | No modo web, omita `image_urls` e use `image_with_roles`. |
| `` `image_with_roles[0].role` must be style or subject for kling-v4-long-image `` | Use apenas `style` ou `subject`. |
| `kling-v4-long-image supports at most 1 image with role style` | No máximo uma imagem por função; sujeito duplicado também é inválido. |
| `` `resolution` must be 1K or 2K for kling-v4-long-image `` | Use `1K` ou `2K`. |
| `` `size` is not supported by kling-v4-long-image `` | Remova os campos não suportados de tamanho, proporção ou série; não envie `null` nem string vazia. |
| `` `n` is not supported by kling-v4-long-image: each request returns one long image `` | Omita `n` ou use o inteiro `1`. |
| `reference image is not accessible for kling-v4-long-image` | Verifique acesso público, validade e respostas 403 / 404 / 410. |
| `unsupported reference image dimensions for kling-v4-long-image` | Pelo menos 300 px por lado e proporção de 2:5 a 5:2. |
| `reference image too large for kling-v4-long-image` | No máximo 30 MB por referência. |


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