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"
}
}
Grok Imagine 2.0 Ext
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
POST
/
v1
/
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
O nome do modelo é fixo:
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.Para camadas de objetos ou edição de regiões selecionadas, consulte Camadas e edição de regiões.
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-extboolean
padrão:"false"
Define se o conteúdo deve ser moderado antes do envio da tarefa de imagem.
true: verificar prompts e imagens de entrada comomni-moderation-latestfalseou omitido: não enviar solicitação de moderação, sem custo nem latência adicionais de moderação (padrão)
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):
Aliases de pixels:
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 |
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
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 |
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"
}
Recomendado
{
"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
PrefiraX-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.idpara consulta (polling)request_idpara depuração no gateway- o
Idempotency-Keypara 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 fortementeIdempotency-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 |
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 |
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; quandon>1, percorra todas as entradas - Pareie por índice somente se
image_ids.length === url.length image_idsausente 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_secretestiver definido, a assinatura éhex(HMAC-SHA256(secret, raw_body))sobre os bytes brutos - O corpo do callback corresponde ao
datada 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 |
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 |