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

# Grok Imagine 2.0 Ext geração de imagens

>  - Texto para imagem assíncrono; consulte com task_id
- 1–12 imagens por solicitação; cobrança por imagem entregue com sucesso ($0.08 cada)
- Saída apenas em URL; sem imagem para imagem / streaming
- URLs de imagem expiram em 72 horas 

<Info>
  **Texto para imagem · tarefas assíncronas.** Envie `POST /v1/images/generations` e, em seguida, consulte [Obter status da tarefa](/pt/api-reference/tasks/status).\
  O nome do modelo é fixo: `grok-imagine-2.0-ext`. **Não suportado**: imagens de referência, `stream` ou valores de `response_format` diferentes de `url`.
</Info>

<Warning>
  Não coloque chaves de API em bundles do navegador (`VITE_*` / `NEXT_PUBLIC_*`, LocalStorage etc.). Prefira chamar seu próprio BFF a partir do navegador; mantenha a chave APIMart no servidor.
</Warning>

<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' \
    --header 'Accept: application/json' \
    --header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
    --header 'X-APIMart-Response-Version: 2026-07-27' \
    --data '{
      "model": "grok-imagine-2.0-ext",
      "prompt": "A red apple on a white ceramic plate, clean studio product photo",
      "n": 1,
      "size": "1:1",
      "resolution": "quality",
      "response_format": "url"
    }'
  ```

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

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

  payload = {
      "model": "grok-imagine-2.0-ext",
      "prompt": "A red apple on a white ceramic plate, clean studio product photo",
      "n": 1,
      "size": "1:1",
      "resolution": "quality",
      "response_format": "url",
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
      "Accept": "application/json",
      "Idempotency-Key": str(uuid.uuid4()),
      "X-APIMart-Response-Version": "2026-07-27",
  }

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

  print(response.status_code, response.json())
  ```

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

  const payload = {
    model: "grok-imagine-2.0-ext",
    prompt: "A red apple on a white ceramic plate, clean studio product photo",
    n: 1,
    size: "1:1",
    resolution: "quality",
    response_format: "url",
  };

  const headers = {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
    Accept: "application/json",
    "Idempotency-Key": crypto.randomUUID(),
    "X-APIMart-Response-Version": "2026-07-27",
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload),
  })
    .then(async (response) => {
      console.log(response.status, await response.json());
    })
    .catch((error) => console.error("Error:", error));
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "code": 202,
    "request_id": "2026081111342261665927mpb4IPDb",
    "data": {
      "id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
      "object": "generation.task",
      "type": "image",
      "status": "pending",
      "progress": 0,
      "poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "request_id": "20260811...",
    "error": {
      "message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
      "type": "invalid_response_format",
      "param": "",
      "code": "invalid_response_format"
    }
  }
  ```

  ```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 and try again",
      "type": "payment_required"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Too many requests. Please try again later",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## Capacidades e limites

| Dimensão       | Contrato                                                                             |
| -------------- | ------------------------------------------------------------------------------------ |
| Modelo         | Fixo `grok-imagine-2.0-ext`                                                          |
| Capacidade     | **Somente texto para imagem**                                                        |
| Modo           | Tarefa assíncrona                                                                    |
| Quantidade `n` | `1`–`12`, padrão `1`                                                                 |
| `size`         | 7 proporções + 5 aliases de pixels (abaixo)                                          |
| Saída          | Apenas `response_format=url` (também o padrão)                                       |
| Qualidade      | Campo público `resolution`; valor verificado `quality`                               |
| Não suportado  | Imagem para imagem, `stream=true`, `quality` público, `style`, `b64_json` / `base64` |
| Cobrança       | Preço unitário fixo; cobra imagens **entregues com sucesso**                         |

## Autenticação e headers recomendados

<ParamField header="Authorization" type="string" required>
  Token Bearer. Obtenha uma chave na [página de API Key](https://apimart.ai/keys).

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

| Header                       | Notas                                                                                                                                       |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`               | `application/json` (envio)                                                                                                                  |
| `Accept`                     | `application/json`                                                                                                                          |
| `Idempotency-Key`            | Fortemente recomendado. Novo UUID por geração confirmada pelo usuário; retentativas de rede **devem reutilizar** a mesma key e o mesmo body |
| `X-APIMart-Response-Version` | Prefira `2026-07-27` para um formato estável de envio (`data.id`)                                                                           |

## Parâmetros da solicitação

<ParamField body="model" type="string" required>
  Valor fixo: `grok-imagine-2.0-ext`
</ParamField>

<ParamField body="prompt" type="string" required>
  Prompt. Deve ser não vazio após trim. Faça trim antes de enviar.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Quantidade de imagens: `1`–`12`. `0` explícito gera erro. Omita para `1`.
</ParamField>

<ParamField body="size" type="string">
  Proporção da imagem. **Prefira strings de proporção** (a UI deve mostrar apenas proporções):

  | `size` | Orientação | Uso típico                  |
  | ------ | ---------- | --------------------------- |
  | `1:1`  | Quadrado   | Produto, avatar             |
  | `2:3`  | Retrato    | Poster, corpo inteiro       |
  | `3:2`  | Paisagem   | Foto, cena ampla            |
  | `3:4`  | Retrato    | E-commerce, pessoas         |
  | `4:3`  | Paisagem   | Arte de exibição            |
  | `9:16` | Vertical   | Capa de Story / vídeo curto |
  | `16:9` | Largo      | Banner, capa de vídeo       |

  Aliases de pixels: `1024x1024` (1:1), `1024x1792` (2:3), `1792x1024` (3:2), `720x1280` (9:16), `1280x720` (16:9).

  Valores fora da lista branca retornam `400 invalid_size` (ex.: `1:2`, `2:1`, `4:5`, `auto`).

  <Note>
    Os pixels reais de uma proporção podem diferir da tabela de aliases (ex.: `1:1` pode retornar 1408×1408). Confie na imagem retornada; não reescreva `size` a partir dos pixels medidos.
  </Note>
</ParamField>

<ParamField body="resolution" type="string">
  Campo de modo de qualidade. Valor verificado: `quality`.

  * Omita (o modelo é modo qualidade por padrão), ou
  * Passe `resolution: "quality"` explicitamente

  **Não** é um nível de pixels `1K` / `2K` / `4K`; o enquadramento é controlado por `size`.

  <Warning>
    Não envie o campo público `quality` — você recebe `400 invalid_quality`. Use `resolution`.
  </Warning>
</ParamField>

<ParamField body="response_format" type="string" default="url">
  Apenas `url` é permitido. Pode ser omitido. `b64_json` / `base64` → `400 invalid_response_format`.
</ParamField>

<ParamField body="webhook" type="string">
  **URL base** HTTPS pública opcional. No status terminal, a plataforma faz POST em `{webhook}/callback`. Somente no servidor — veja [Webhook](#webhook-opcional).
</ParamField>

### Parâmetros não suportados

| Parâmetro                                  | Comportamento                            |
| ------------------------------------------ | ---------------------------------------- |
| `quality`                                  | `400 invalid_quality` → use `resolution` |
| `style`                                    | `400 invalid_style`                      |
| `image_urls` / `image_with_roles`          | `400 invalid_image_input`                |
| `stream: true`                             | `400 invalid_stream`                     |
| `response_format: "b64_json"` / `"base64"` | `400 invalid_response_format`            |

Monte as solicitações com uma lista branca; não encaminhe um objeto de formulário genérico de outros modelos de imagem.

## Exemplos de solicitação

### Mínimo

```json theme={null}
{
  "model": "grok-imagine-2.0-ext",
  "prompt": "A red apple on a white ceramic plate, clean studio product photo"
}
```

### Recomendado

```json theme={null}
{
  "model": "grok-imagine-2.0-ext",
  "prompt": "A red apple on a white ceramic plate, clean studio product photo",
  "n": 1,
  "size": "1:1",
  "resolution": "quality",
  "response_format": "url"
}
```

## Resposta de envio

Prefira `X-APIMart-Response-Version: 2026-07-27`. Sucesso é HTTP **`202`**; o id da tarefa é **`data.id`** (não dependa do legado `data[0].task_id`).

Persista:

* `data.id` para consulta (polling)
* `request_id` para depuração no gateway
* o `Idempotency-Key` para retentativas seguras quando o resultado for desconhecido
* parâmetros originais da solicitação para UI / suporte

## Idempotência e retentativas seguras

A geração de imagens é cobrável — **recomenda-se fortemente** `Idempotency-Key` (1–191 caracteres ASCII imprimíveis; UUID é o mais simples; retido \~24 horas).

| Cenário                             | Comportamento                                 | Ação                                                       |
| ----------------------------------- | --------------------------------------------- | ---------------------------------------------------------- |
| Mesma key + mesmo body já concluído | Replay; header `Idempotency-Replayed: true`   | Use o mesmo id da tarefa                                   |
| Mesma key ainda em andamento        | `409 idempotency_in_progress` + `Retry-After` | Aguarde e tente de novo com a **mesma key e o mesmo body** |
| Mesma key, body diferente           | `409 idempotency_key_reused`                  | Nova tarefa lógica precisa de nova key                     |
| Resultado indeterminado             | `409 idempotency_result_indeterminate`        | Não crie uma key nova; investigue com a antiga             |

Em timeout de rede no POST quando não for possível saber se o servidor aceitou a tarefa, **não crie imediatamente uma key nova** — tente de novo com a mesma key / body / versão de resposta.

## Consultar tarefas

```http theme={null}
GET /v1/tasks/{task_id}?language=en
Authorization: Bearer YOUR_API_KEY
Accept: application/json
```

`language` opcional: `zh` / `en` / `ko` / `ja` (apenas localização de mensagens de falha). Veja [Obter status da tarefa](/pt/api-reference/tasks/status).

### Status

| `status`                 | Terminal | Tratamento                                                              |
| ------------------------ | :------: | ----------------------------------------------------------------------- |
| `pending` / `processing` |    Não   | Continue consultando (`result` pode estar ausente — não é falha)        |
| `completed`              |    Sim   | Analise `result.images`                                                 |
| `failed`                 |    Sim   | Exiba `error.message`; `cost` é `0` (pré-cobrança reembolsada)          |
| `unknown`                |    Não   | Retentativas curtas; se persistir, contate o suporte com o id da tarefa |

Consulte a cada **2 segundos** aproximadamente; limite próximo de **10 minutos** ou **120** tentativas. Respeite `Retry-After` em `429`. As tarefas são mantidas \~3 dias por padrão — guarde o id da tarefa se o cliente atingir timeout.

### Exemplo de conclusão

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
    "status": "completed",
    "progress": 100,
    "created": 1786419262,
    "completed": 1786419275,
    "actual_time": 13,
    "estimated_time": 100,
    "cost": 0.08,
    "credits_cost": 0.8,
    "result": {
      "images": [
        {
          "expires_at": 1786505675,
          "url": [
            "https://example.com/image/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jpg"
          ],
          "image_ids": [
            "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          ]
        }
      ]
    }
  }
}
```

### Analisando `url` e `image_ids`

```text theme={null}
result.images[]
  ├─ url[]          ← authoritative display/download field (array)
  ├─ image_ids[]    ← optional opaque IDs
  └─ expires_at     ← Unix seconds; multiply by 1000 for JS Date
```

1. Use `url[]` para exibição; quando `n>1`, percorra todas as entradas
2. Pareie por índice somente se `image_ids.length === url.length`
3. `image_ids` ausente ainda permite exibição
4. Links duram **72 horas** — baixe com rapidez; confie também em `expires_at`

## Cobrança

Preço base **\$0.08 por imagem** (entregas bem-sucedidas):

| `n` | Base estimada |
| --: | ------------: |
|   1 |        \$0.08 |
|   4 |        \$0.32 |
|   8 |        \$0.64 |
|  12 |        \$0.96 |

* A UI pré-envio deve dizer “estimativa”; o USD final é **`data.cost`**
* **`data.credits_cost`** é a visão em créditos (atualmente \~ USD × 10)
* Pré-cobrança pela quantidade solicitada; acerto pela quantidade bem-sucedida (reembolsos parciais em falha parcial)
* Falha total: `cost=0`, pré-cobrança reembolsada
* Não monte chaves de preço a partir de `resolution`; este modelo tem preço fixo por imagem

## Webhook (opcional)

```json theme={null}
{
  "webhook": "https://your-service.example.com/apimart"
}
```

* Forneça uma **URL base**; a plataforma chama `{base}/callback`
* Deve ser pública e passar nas verificações SSRF
* Se `webhook_secret` estiver definido, a assinatura é `hex(HMAC-SHA256(secret, raw_body))` sobre os bytes brutos
* O corpo do callback corresponde ao `data` da consulta de tarefa (sem wrapper extra `{code,data}`)
* Ainda mantenha polling de baixa frequência como fallback

## Erros comuns

| HTTP | `error.code`              | Causa                           | Ação                                               |
| ---: | ------------------------- | ------------------------------- | -------------------------------------------------- |
|  400 | `invalid_request`         | Prompt vazio / JSON inválido    | Valide a entrada                                   |
|  400 | `invalid_n`               | `n` fora de 1–12                | Limite a quantidade                                |
|  400 | `invalid_size`            | Size fora da lista branca       | Opções fixas de seleção                            |
|  400 | `invalid_response_format` | Não é `url`                     | Corrija ou omita                                   |
|  400 | `invalid_quality`         | Campo público `quality` enviado | Use `resolution`                                   |
|  400 | `invalid_style`           | `style` enviado                 | Remova                                             |
|  400 | `invalid_image_input`     | Imagens de referência           | Troque de modelo                                   |
|  400 | `invalid_stream`          | `stream=true`                   | Remova                                             |
|  400 | `invalid_idempotency_key` | Key inválida                    | Use UUID                                           |
|  401 | Falha de autenticação     | Key inválida                    | Corrija as credenciais no servidor                 |
|  402 | Pagamento necessário      | Saldo baixo                     | Recarregue                                         |
|  409 | `idempotency_*`           | Conflito de idempotência        | Veja a tabela acima                                |
|  429 | Limite de taxa            | Muito rápido                    | Respeite `Retry-After`                             |
|  5xx | Erro do servidor          | —                               | Mantenha o Idempotency-Key; não rotacione às cegas |

Prefira `error.message` na UI. Não exponha detalhes internos de autenticação aos usuários finais.

## Diferenças em relação à 1.5 (resumo)

| Item               | Grok Imagine 1.5                   | 2.0 Ext                                           |
| ------------------ | ---------------------------------- | ------------------------------------------------- |
| Modelo             | `grok-imagine-1.5-apimart`, etc.   | `grok-imagine-2.0-ext`                            |
| Imagem para imagem | Suportado (veja docs 1.5)          | **Não suportado**                                 |
| Quantidade         | Veja docs 1.5                      | **1–12**                                          |
| Campo de qualidade | Veja docs 1.5                      | `resolution` (`quality`); nunca `quality` público |
| Saída              | Veja docs 1.5                      | **Somente URL**                                   |
| TTL da URL         | Veja docs 1.5 (frequentemente 24h) | **72 horas**                                      |
| Preço unitário     | Veja docs 1.5                      | **\$0.08 / imagem**                               |