> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/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 

> [!NOTE]
>
> **Texto para imagem · tarefas assíncronas.** Envie `POST /v1/images/generations` e, em seguida, consulte [Obter status da tarefa](https://gccai.heqingsong.uk/pt/api-reference/tasks/status.md).\
> 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`.

> [!NOTE]
>
> Para camadas de objetos ou edição de regiões selecionadas, consulte [Camadas e edição de regiões](https://gccai.heqingsong.uk/pt/api-reference/images/grok-imagine-2.0-ext/layer-region-edit.md).

> [!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 GccAi no servidor.

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/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-GccAi-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://gccai.heqingsong.uk/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-GccAi-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://gccai.heqingsong.uk/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-GccAi-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));
```

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

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

**Authorization** `string` *required*

Token Bearer. Obtenha uma chave na [página de API Key](https://gccai.heqingsong.uk/keys).

```
Authorization: Bearer YOUR_API_KEY
```

| 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-GccAi-Response-Version` | Prefira `2026-07-27` para um formato estável de envio (`data.id`) |

## Parâmetros da solicitação

**model** `string` *required*

Valor fixo: `grok-imagine-2.0-ext`

**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*

Prompt. Deve ser não vazio após trim. Faça trim antes de enviar.

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

Quantidade de imagens: `1`–`12`. `0` explícito gera erro. Omita para `1`.

**size** `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.

**resolution** `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`.

**response\_format** `string` (default: url)

Apenas `url` é permitido. Pode ser omitido. `b64_json` / `base64` → `400 invalid_response_format`.

**webhook** `string`

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

### 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-GccAi-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](https://gccai.heqingsong.uk/pt/api-reference/tasks/status.md).

### 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/gccai"
}
```

* 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-gccai`, 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** |


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