> ## 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 e edição de imagens com FLUX Kontext

> Envie tarefas assíncronas do FLUX Kontext para geração ou edição de imagens. A API retorna um ID de tarefa; consulte o endpoint de tarefas para obter a imagem gerada.

<RequestExample>
  ```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": "flux-kontext-pro",
      "prompt": "Change the hair color to blue",
      "image_urls": ["https://example.com/portrait.jpg"],
      "size": "1:1",
      "output_format": "png"
    }'
  ```

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

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "flux-kontext-pro",
      "prompt": "Change the hair color to blue",
      "image_urls": ["https://example.com/portrait.jpg"],
      "size": "1:1",
      "output_format": "png"
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "flux-kontext-pro",
    prompt: "Change the hair color to blue",
    image_urls: ["https://example.com/portrait.jpg"],
    size: "1:1",
    output_format: "png"
  };

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  });

  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentication failed, please check your API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Insufficient balance, please top up",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## Modelos compatíveis

| Modelo             | Descrição                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `flux-kontext-pro` | Geração e edição de imagens com reconhecimento de contexto para fluxos de trabalho em geral. |
| `flux-kontext-max` | Geração e edição de imagens com reconhecimento de contexto e qualidade superior.             |

Os dois modelos permitem gerar imagens a partir de texto sem imagens de referência ou editar imagens usando referências.

## Autenticação

<ParamField header="Authorization" type="string" required>
  Todos os endpoints exigem autenticação com token Bearer.

  Obtenha uma chave de API em [Gerenciamento de chaves de API](https://apimart.ai/keys) e adicione-a ao cabeçalho da requisição:

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Corpo da requisição

<ParamField body="model" type="string" required>
  Nome do modelo:

  * `flux-kontext-pro`
  * `flux-kontext-max`
</ParamField>

<ParamField body="prompt" type="string" required>
  Descrição textual da imagem a ser gerada ou da edição a ser aplicada às imagens de referência.
</ParamField>

<ParamField body="image_urls" type="array">
  Imagens de referência para edição. Forneça-as por URL acessível publicamente ou em Base64.

  * Máximo: 4 imagens
  * A soma da saída com todas as imagens de referência não pode ultrapassar 9 MP

  Se uma URL de referência estiver inacessível, a tarefa pode retornar `temporarily unavailable dependency`; nesse caso, verifique primeiro se a URL é pública, não está expirada e não bloqueia acesso externo.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  Proporção da imagem de saída. Valores compatíveis:

  * `1:1` (padrão)
  * `4:3`
  * `3:4`
  * `16:9`
  * `9:16`
  * `3:2`
  * `2:3`
  * `21:9`
  * `9:21`

  Também é possível informar uma string de pixels, como `1024x1536`; o Kontext a converte para a proporção compatível mais próxima, sem garantir essas dimensões exatas.

  O parâmetro `resolution` não altera a saída do Kontext, que permanece em torno de 1 MP. Não envie `width` nem `height`: esses parâmetros não são compatíveis com o Kontext e fazem a tarefa falhar.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  Formato da imagem de saída: `png`, `jpeg` ou `webp`. O padrão é `png`.
</ParamField>

<ParamField body="response_format" type="string">
  Parâmetro de compatibilidade para a forma da resposta. Valores aceitos: `url` e `b64_json`. Ele não altera o formato da imagem; se `output_format` também for enviado, `output_format` terá prioridade.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Número de imagens geradas. Somente o valor `1` é aceito.
</ParamField>

<ParamField body="seed" type="integer">
  Semente aleatória. Reutilize a mesma semente e os mesmos parâmetros para obter resultados reproduzíveis; omita-a para usar uma semente aleatória.
</ParamField>

<ParamField body="prompt_upsampling" type="boolean" default="false">
  Indica se o prompt deve ser aprimorado e reescrito antes da geração.

  Defina este parâmetro explicitamente como `false` para desativar a reescrita do prompt.
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  Tolerância de segurança de `0` a `6`. Valores mais altos são mais permissivos.
</ParamField>

## Proporções compatíveis

| Proporção | Orientação             |
| --------- | ---------------------- |
| `1:1`     | Quadrado (padrão)      |
| `4:3`     | Paisagem               |
| `3:4`     | Retrato                |
| `16:9`    | Paisagem em tela ampla |
| `9:16`    | Retrato vertical       |
| `3:2`     | Paisagem clássica      |
| `2:3`     | Retrato clássico       |
| `21:9`    | Paisagem ultra-ampla   |
| `9:21`    | Retrato ultra-alto     |

### Dimensões reais da saída

| Proporção | Dimensões reais |
| --------- | --------------- |
| `1:1`     | 1024×1024       |
| `4:3`     | 1184×880        |
| `3:4`     | 880×1184        |
| `16:9`    | 1392×752        |
| `9:16`    | 752×1392        |
| `3:2`     | 1248×832        |
| `2:3`     | 832×1248        |
| `21:9`    | 1568×672        |
| `9:21`    | 672×1568        |

## Exemplos de uso

### Geração de texto para imagem

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "A cozy reading nook with warm lamplight",
  "size": "4:3"
}
```

### Edição de imagem

```json theme={null}
{
  "model": "flux-kontext-max",
  "prompt": "Replace the background with a beach while preserving the person",
  "image_urls": ["https://example.com/portrait.jpg"],
  "size": "16:9",
  "output_format": "webp"
}
```

### Várias imagens de referência

```json theme={null}
{
  "model": "flux-kontext-pro",
  "prompt": "Place the product from the first image into the room from the second image",
  "image_urls": [
    "https://example.com/product.jpg",
    "https://example.com/room.jpg"
  ],
  "size": "4:3"
}
```

## Resposta

<ResponseField name="code" type="integer">
  Código de status da resposta.
</ResponseField>

<ResponseField name="data" type="array">
  Array com o resultado do envio.

  <Expandable title="Propriedades">
    <ResponseField name="status" type="string">
      Status do envio. Uma tarefa aceita com sucesso retorna `submitted`.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Identificador exclusivo da tarefa. Use-o para consultar o endpoint de tarefas.
    </ResponseField>
  </Expandable>
</ResponseField>

## Recuperar o resultado

Consulte `GET /v1/tasks/{task_id}` até que a tarefa atinja o status `completed` ou `failed`. Consulte a [API de status de tarefas](/pt/api-reference/tasks/status) para ver o esquema completo da resposta.

Uma tarefa concluída contém uma imagem gerada:

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://upload.apimart.ai/f/image/xxxxxxxx-flux-kontext.png"],
          "expires_at": 1785220083
        }
      ]
    }
  }
}
```

A URL da imagem está em `data.result.images[0].url[0]`. A expiração é definida pelo timestamp Unix em `data.result.images[0].expires_at`; baixe a imagem antes desse momento.

### Status da tarefa

| Status                  | Significado                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `submitted` / `pending` | A tarefa foi aceita ou está na fila; continue consultando                                    |
| `processing`            | A imagem está sendo gerada; continue consultando                                             |
| `completed`             | A tarefa foi concluída; o resultado está em `result.images`                                  |
| `failed`                | A tarefa falhou; o motivo está em `data.error.message` e o valor é reembolsado integralmente |

Exemplo de uma tarefa com falha:

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "width/height are not supported by flux-kontext-pro"
    }
  }
}
```

Parâmetros de modelo inválidos não retornam um erro 400 síncrono. O envio retorna HTTP 200 e um `task_id`; durante a consulta, a tarefa passa para `failed`. O motivo específico está sempre em `error.message`, enquanto `error.code` é `task_failed`. Tarefas que falham são reembolsadas integralmente.

## Observações

1. As tarefas são processadas de forma assíncrona. A resposta ao envio retorna um `task_id` para consultar o status.
2. O parâmetro `n` deve ser `1`; cada requisição gera exatamente uma imagem.
3. As imagens de referência podem ser fornecidas por URL acessível publicamente ou em Base64.
4. São permitidas até 4 imagens de referência, e a soma da saída com todas as referências não pode ultrapassar 9 MP.
5. Defina explicitamente `prompt_upsampling: false` para desativar a reescrita do prompt.
6. A expiração da URL do resultado é determinada pelo valor de `expires_at` retornado na resposta da tarefa.