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

> Gere imagens a partir de texto ou de até 10 imagens de referência e séries de 2–4 imagens relacionadas. O modo padrão produz 1–9 imagens PNG em 2K / 4K / 8K 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-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"
  }
}
```

Envie uma solicitação assíncrona para `POST /v1/images/generations` com `model: "kling-v4-image"`. Obtenha `data[0].task_id` e consulte o resultado com `GET /v1/tasks/{task_id}`.

## 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-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 para geração a partir de texto, de imagens e em série. Descreva o conteúdo desejado e o que deve ser evitado. O limite é de 50.000 caracteres para texto apenas em inglês e 21.000 para texto apenas em chinês ou idiomas semelhantes; textos mistos são calculados proporcionalmente.

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

Até 10 imagens de referência por URLs diretas acessíveis publicamente. 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.

Aceita JPG / JPEG / PNG / GIF. Cada imagem deve ter no máximo 30 MB, largura e altura de pelo menos 300 px e proporção entre 2:5 e 5:2.

As referências são verificadas no envio. Uma URL que retorna HTTP 403 / 404 / 410, um lado menor que 300 px, uma proporção fora de 2:5–5:2 ou uma imagem maior que 30 MB retorna HTTP 400 imediatamente, sem criar tarefa nem cobrar a geração. Outras falhas ao obter a imagem, como tempo limite do servidor de origem, são aceitas inicialmente; a tarefa falha depois e os valores de geração descontados antecipadamente são reembolsados integralmente.

Use `@Image1`, `@Image2` etc. no prompt para indicar as imagens na ordem do array. Elas também são usadas como referência sem esses marcadores.

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

Quantidade de saídas no modo padrão: inteiro de 1 a 9, padrão 1. No modo série, `n` pode ser omitido ou definido como `1`; `sequential_image_generation_options.max_images` determina a quantidade de saídas. Enviar `n > 1` em uma série retorna HTTP 400.

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

Aceita `2K` (padrão), `4K` e `8K`, sem distinguir maiúsculas de minúsculas. A saída é PNG. Em `1:1`, 2K corresponde a `2048×2048`, 4K a `4096×4096` e 8K a `8192×8192`. Para outras proporções, consulte as dimensões reais das imagens retornadas.

8K também permite geração a partir de texto, de imagens e em série: 1–9 saídas no modo padrão, 2–4 em série e até 10 imagens de referência. Os formatos, dimensões e o limite de 30 MB por imagem de referência permanecem iguais.

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

Proporção da saída. Aceita `auto` (padrão) e estas 8 proporções:

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

`auto` escolhe a proporção com base no prompt ou nas referências. Dimensões em pixels como `2048x2048` não são aceitas.

**aspect\_ratio** `string`

Alias de `size` com os mesmos valores. Se ambos forem enviados, `aspect_ratio` tem prioridade.

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

`disabled` ou a omissão do campo ativa a geração padrão. `auto` gera uma série de imagens relacionadas e exige `sequential_image_generation_options.max_images`. Aqui, `auto` não decide automaticamente a quantidade de imagens.

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

Define a quantidade de imagens no modo série.

**Propriedades**

**max\_images** `integer`

Obrigatório no modo série: inteiro de 2 a 4 que define a quantidade de saída solicitada. Omitir, enviar a string `"auto"` ou um valor fora do intervalo retorna HTTP 400.

> [!WARNING]
>
> `width`, `height`, `mask_url`, `size` em pixels e `watermark: true` não são suportados e retornam HTTP 400.

## Exemplos de solicitação

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

### Geração a partir de imagem

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

### Gerar três imagens 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
}'
```

### Gerar uma imagem 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
}'
```

### Gerar uma série de quatro imagens 8K relacionadas

Defina `max_images` entre 2 e 4. Em série, `n` pode ser omitido ou definido como `1`, mas não pode ser maior que `1`. Uma série pode levar vários minutos; guarde o `task_id` e consulte o status para evitar envios 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"
}'
```

## Exemplos de saída 8K e tempo de processamento

As medições abaixo são amostras do ambiente de teste. Dimensões, tamanhos de arquivo e tempos são ilustrativos; os resultados reais podem variar.

| Solicitação 8K | Dimensões de saída | Tamanho do arquivo por imagem | Tempo até a conclusão |
| - | - | - | - |
| 1 imagem no modo padrão (16:9) | `10880×6144` | 117 MB | Cerca de 2,5 minutos |
| 4 / 9 imagens no modo padrão (1:1) | `8192×8192` | 100–130 MB | Cerca de 3 minutos |
| Série de 4 imagens (3:4) | `7040×9344` | 77–104 MB | Cerca de 6 minutos |

Consulte a cada 5–10 segundos até `completed` ou `failed`. `estimated_time` é fixo em 60 segundos e não deve ser usado como estimativa real ou contagem regressiva. Guarde o `task_id` e evite reenviar a solicitação enquanto aguarda.

Os resultados 8K são PNGs originais, e um arquivo pode ultrapassar 100 MB. Em listas e prévias, use miniaturas geradas por você ou carregue as imagens sob demanda. Ofereça o download do original e informe que o arquivo é grande.

## Consultar a tarefa

Leia `data.status` pela [API de consulta de tarefas](https://docs.apimart.ai/pt/api-reference/tasks/status.md): `pending` / `processing` indica processamento, `completed` indica sucesso e `failed` indica falha, com detalhes em `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>'
```

A seguir está a estrutura de um resultado bem-sucedido. As URLs estão em `data.result.images[].url[]`; `url` é um array. Percorra todas as saídas e baixe-as assim que possível.

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

## Cobrança

A cobrança considera a quantidade real de imagens geradas e a resolução escolhida. As referências são cobradas separadamente por imagem. Consulte a [página de preços](https://apimart.ai/pricing).

| Item de cobrança | Chave de preço |
| - | - |
| Cada imagem de saída 2K | `kling-v4-image@2K` |
| Cada imagem de saída 4K | `kling-v4-image@4K` |
| Cada imagem de saída 8K | `kling-v4-image@8K` |
| Cada imagem de referência de entrada | `kling-v4-image@input` |

* Na geração padrão, `n=3` equivale a 3 saídas cobradas; em séries, usa-se a quantidade realmente retornada.
* Cada referência é contada uma vez por solicitação, sem multiplicação pela quantidade de saídas. Gerar 3 imagens com 2 referências resulta em 2 entradas e 3 saídas cobradas.
* Tarefas de geração que falham não são cobradas; os valores de geração descontados antecipadamente são reembolsados integralmente.

## Erros comuns de parâmetros

Estes erros retornam HTTP 400 de forma síncrona no envio, sem criar tarefa nem cobrar a geração. Leia `error.message` para erros no envio e `data.error.message` para falhas após a criação da tarefa.

| Trecho do erro | Solução |
| - | - |
| `` `prompt` is required for kling-v4-image `` | Forneça um prompt não vazio. |
| `` `n` must be an integer between 1 and 9 `` | Use um inteiro de 1 a 9 para `n`. |
| `` `n` cannot be combined with sequential_image_generation=auto `` | No modo série, omita `n` ou defina-o como `1`; use `max_images` para controlar a quantidade de saídas. |
| `` `sequential_image_generation_options.max_images` is required for kling-v4-image series mode `` | Forneça `max_images` ao ativar a série. |
| `` `sequential_image_generation_options.max_images` must be an integer between 2 and 4 `` | Use um inteiro de 2 a 4, não `"auto"`. |
| `` `resolution` must be 2K, 4K or 8K for kling-v4-image `` | Use `2K`, `4K` ou `8K`; não há distinção entre maiúsculas e 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 `` | Use `auto` ou uma proporção aceita, não dimensões em pixels. |
| `kling-v4-image supports at most 10 reference images` | Forneça no máximo 10 referências. |
| `reference image is not accessible for kling-v4-image` | A URL de referência retornou 403 / 404 / 410. Verifique se ela é pública e válida ou envie a imagem novamente. |
| `unsupported reference image dimensions for kling-v4-image` | Largura e altura devem ter pelo menos 300 px, com proporção entre 2:5 e 5:2. Erros de proporção usam o mesmo prefixo. |
| `reference image too large for kling-v4-image` | Cada referência deve ter no máximo 30 MB. Comprima antes de enviar novamente. |
| `` `n` must be an integer between 1 and 9 for kling-v4-image (got: "3") `` | Use um inteiro JSON como `"n": 3`, não a string `"3"`. Os demais campos também devem usar o tipo declarado: string, array ou booleano. |


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