Grok Imagine 2.0 Ext geração de imagens

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

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())

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));

{
  "code": 202,
  "request_id": "2026081111342261665927mpb4IPDb",
  "data": {
    "id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
    "object": "generation.task",
    "type": "image",
    "status": "pending",
    "progress": 0,
    "poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
  }
}

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

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Please check your API key",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient balance. Please top up and try again",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "Too many requests. Please try again later",
    "type": "rate_limit_error"
  }
}

POST

images

generations

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

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())

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));

{
  "code": 202,
  "request_id": "2026081111342261665927mpb4IPDb",
  "data": {
    "id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
    "object": "generation.task",
    "type": "image",
    "status": "pending",
    "progress": 0,
    "poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
  }
}

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

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Please check your API key",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient balance. Please top up and try again",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "Too many requests. Please try again later",
    "type": "rate_limit_error"
  }
}

Texto para imagem · tarefas assíncronas. Envie POST /v1/images/generations e, em seguida, consulte Obter status da tarefa.
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.

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.

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

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())

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));

{
  "code": 202,
  "request_id": "2026081111342261665927mpb4IPDb",
  "data": {
    "id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
    "object": "generation.task",
    "type": "image",
    "status": "pending",
    "progress": 0,
    "poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
  }
}

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

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Please check your API key",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient balance. Please top up and try again",
    "type": "payment_required"
  }
}

{
  "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

string

obrigatório

Token Bearer. Obtenha uma chave na página de API Key.

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

Parâmetros da solicitação

string

obrigatório

Valor fixo: grok-imagine-2.0-ext

string

obrigatório

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

integer

padrão:"1"

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

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

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.

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.

Não envie o campo público quality — você recebe 400 invalid_quality. Use resolution.

string

padrão:"url"

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

string

URL base HTTPS pública opcional. No status terminal, a plataforma faz POST em {webhook}/callback. Somente no servidor — veja Webhook.

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

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

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

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.

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

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

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

Use url[] para exibição; quando n>1, percorra todas as entradas
Pareie por índice somente se image_ids.length === url.length
image_ids ausente ainda permite exibição
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)

{
  "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

Visão Geral

Série de Texto

Série de Imagem

Série de Vídeo

Série de Áudio

Série de Moderação

Gerenciamento de Upload

Gerenciamento de Tarefas

Gerenciamento de Conta

Grok Imagine 2.0 Ext geração de imagens

Capacidades e limites

Autenticação e headers recomendados

Parâmetros da solicitação

Parâmetros não suportados

Exemplos de solicitação

Mínimo

Recomendado

Resposta de envio

Idempotência e retentativas seguras

Consultar tarefas

Status

Exemplo de conclusão

Analisando `url` e `image_ids`

Cobrança

Webhook (opcional)

Erros comuns

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

​Capacidades e limites

​Autenticação e headers recomendados

​Parâmetros da solicitação

​Parâmetros não suportados

​Exemplos de solicitação

​Mínimo

​Recomendado

​Resposta de envio

​Idempotência e retentativas seguras

​Consultar tarefas

​Status

​Exemplo de conclusão

​Analisando url e image_ids

​Cobrança

​Webhook (opcional)

​Erros comuns

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

Capacidades e limites

Autenticação e headers recomendados

Parâmetros da solicitação

Parâmetros não suportados

Exemplos de solicitação

Mínimo

Recomendado

Resposta de envio

Idempotência e retentativas seguras

Consultar tarefas

Status

Exemplo de conclusão

Analisando `url` e `image_ids`

Cobrança

Webhook (opcional)

Erros comuns

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