Referência da API

Schema completo da API REST pública. Disponível nos planos Pro e Max. Gere uma chave em /account/api.

Prefere Postman? Baixe nossa coleção v2.1 — cole sua chave gimg_… na variável apiKey.

Autenticação

Todos os endpoints recebem um token Bearer no header Authorization. Os tokens sempre começam com gimg_.

Authorization: Bearer gimg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate limits

600 requisições / hora / chave, máx. 5 em paralelo. Toda resposta inclui:

X-RateLimit-Limit — fixo em 600
X-RateLimit-Remaining — chamadas restantes na janela atual
X-RateLimit-Reset — epoch seconds em que a janela é resetada
Retry-After — segundos até a próxima chamada permitida (apenas em 429)

Idempotência

Passe Idempotency-Key em requisições POST. Enviar a mesma chave duas vezes retorna a geração existente em vez de cobrar créditos em dobro.

POST/api/v1/generate

Envia uma geração text-to-image OU image-edit. Retorna imediatamente com um generationId; consulte /api/v1/generations/:id para o resultado.

Body

promptstring ≤ 4000 charsobrigatório
Descrição em linguagem natural. Terminologia de fotografia (câmera, lente, iluminação) ajuda.
type"text2img" | "edit"
Padrão é 'text2img'. 'edit' exige inputImageKeys.
size"1024x1024" | "1024x1536" | "1536x1024"
Proporção. Padrão é 1024x1024.
quality"low" | "medium" | "high"
Padrão é medium. high = HD 2K. low é Rápido (1cr).
n1–4
Número de variações. Padrão é 1.
inputImageKeysstring[] (max 4)
Chaves R2 retornadas por /api/v1/upload. Obrigatório quando type=edit.

Respostas

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
Body inválido. O erro inclui uma mensagem de validação do Zod.
401 Unauthorizedjson
Chave Bearer ausente ou inválida.
402 Payment Requiredjson
Créditos insuficientes ou limite mensal de compute atingido.
403 Forbiddenjson
Plano Pro/Max obrigatório.
422 Unprocessablejson
Prompt bloqueado pela política de conteúdo.
429 Too Many Requestsjson
Rate limit atingido. Veja Retry-After.

POST/api/v1/upload

Obtém uma URL PUT pré-assinada do R2 para enviar uma imagem de entrada. Em duas etapas: isto retorna a URL, você faz PUT dos bytes diretamente nela.

Body

filenamestring ≤ 200obrigatório
Nome de exibição; não é usado para armazenamento.
contentType"image/png" | "image/jpeg" | "image/webp"obrigatório
Deve ser exatamente um destes três.
sizenumber (bytes ≤ 10 MB)obrigatório
Tamanho do arquivo que você pretende dar PUT. Usado para validação.

Resposta (200)

urlstring
URL PUT pré-assinada, expira em 5 minutos.
keystring
Chave R2 — passe isto em inputImageKeys ao chamar /api/v1/generate.

GET/api/v1/generations/:id

Consulta o status de uma geração. Retorna imediatamente com o estado atual.

Resposta (200)

idstring
O id da geração.
status"queued" | "running" | "succeeded" | "failed" | "blocked"
'blocked' = a moderação de conteúdo rejeitou a entrada ou saída (créditos reembolsados).
typestring
text2img | edit | upscale | …
outputsArray<{ png, webp, width, height }>
Preenchido quando status=succeeded. As URLs são públicas, imutáveis e cacheadas pela CDN.
errorstring | null
Preenchido quando status=failed ou status=blocked.
costCreditsnumber
Créditos cobrados (reembolsados em caso de blocked ou failed).
createdAt / completedAtISO 8601
Timestamps.

Webhooks de saída

Pule o polling: registre endpoints HTTPS para receber eventos generation.succeeded e generation.failed em tempo real. Gerencie em /api/account/webhooks.

Registrar

curl -X POST https://gptimage2.plus/api/account/webhooks \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/gptimg",
    "events": ["generation.succeeded", "generation.failed"],
    "label": "Production app"
  }'
# → { "id": "...", "secret": "whsec_..." }   ← copy this, shown ONCE

Payload do evento

POST https://your-app.com/hooks/gptimg
X-Gptimg-Event: generation.succeeded
X-Gptimg-Signature: <hex sha256 hmac of body>
X-Gptimg-Delivery: <uuid for dedup>
Content-Type: application/json

{
  "event": "generation.succeeded",
  "data": {
    "generationId": "...",
    "type": "text2img",
    "status": "succeeded",
    "outputs": [{ "png": "...", "webp": "...", "width": 1024, "height": 1024 }],
    "createdAt": "2026-04-26T01:23:45.000Z",
    "completedAt": "2026-04-26T01:23:50.000Z"
  }
}

Verificar a assinatura

// Node example
import crypto from "crypto";
const expected = crypto
  .createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-gptimg-signature"])
);

Timeout: 5s por tentativa. Repetimos respostas não-2xx até 3 vezes com backoff exponencial (30s → 2min → 10min). Após 8 falhas consecutivas entre tentativas, o webhook é desativado automaticamente — reative em /account/webhooks.