/api/v1/generate/imageGerar imagem
Geração de imagem a partir de um prompt de texto, no modelo escolhido. Responde
202 Accepted com um taskId; acompanhe o resultado por polling em
GET /api/v1/tasks/:id ou via webhook.
Escopo necessário: generate:image.
Body
| Campo | Tipo | Obrigatório | Valores / restrições | Padrão |
|---|---|---|---|---|
model | string | sim | Um dos modelos disponíveis (ver lista abaixo) | — |
prompt | string | sim | Descrição da imagem a gerar | — |
referenceImages | string[] | não | URLs HTTPS públicas de referência; depende do modelo (alguns não aceitam) | — |
aspectRatio | string | não | Proporção suportada pelo modelo (ex.: 1:1, 9:16, 16:9) | default do modelo |
quality | string | não | Resolução suportada pelo modelo (ex.: 1K, 2K, 4K) | default do modelo |
modelOptions | object | não | Opções extras específicas do modelo (objeto JSON; passado adiante) | {} |
callbackUrl | string | não | HTTPS, host não-privado | — |
Se aspectRatio ou quality forem omitidos, é usado o default daquele modelo (ver tabela abaixo).
Modelos disponíveis
Escolha o modelo no campo model conforme o caso de uso. Cada modelo aceita um
conjunto próprio de proporções, resoluções e imagens de referência.
| Modelo | Quando usar | Refs (máx.) | Proporções (default) | Resoluções (default) |
|---|---|---|---|---|
nano-banana-pro | Melhor escolha ao trabalhar com imagens de referência | 14 | auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default 9:16) | 1K, 2K, 4K (default 1K) |
nano-banana-2 | Versão clássica, de custo menor | 4 | 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default 9:16) | 1K, 2K, 4K (default 1K) |
seedream-4.5 | Prompts longos e cenas complexas | 4 | 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9 (default 9:16) | 1K, 2K, 4K (default 2K) |
gpt-image-2 | Estilo ilustrativo | 8 | auto, 1:1, 5:4, 4:5, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9 (default auto) | 1K, 2K, 4K (default 1K) |
z-image | Geração rápida apenas por texto (sem referências) | 0 | 1:1, 4:3, 3:4, 16:9, 9:16 (default 1:1) | 1K |
grok-imagine | Modelo da xAI; aceita 1 referência opcional | 1 | 1:1, 2:3, 3:2, 9:16, 16:9 (default 3:2) | 1K |
flux-2-pro | Alta fidelidade, com várias referências | 8 | auto, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 (default 1:1) | 1K, 2K (default 1K) |
flux-2-flex | Variante mais rápida do Flux 2 Pro | 8 | auto, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 (default 1:1) | 1K, 2K (default 1K) |
flux-kontext-pro | Edição guiada por instruções em linguagem natural | 1 | 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, 9:21 (default 16:9) | 1K |
flux-kontext-max | Versão Max do Kontext, mais qualidade em cenas complexas | 1 | 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, 9:21 (default 16:9) | 1K |
Enviar uma proporção/resolução não suportada pelo modelo, ou mais imagens de
referência do que ele aceita, retorna 400 VALIDATION_ERROR.
Exemplo de request
curl -X POST https://avatrix.io/api/v1/generate/image \
-H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9f1c-img-001" \
-d '{
"model": "nano-banana-pro",
"prompt": "uma influencer numa cafeteria, luz natural",
"aspectRatio": "9:16",
"quality": "1K"
}'Resposta — 202
{
"success": true,
"data": { "taskId": "...", "status": "queued" }
}O status: "queued" é só o rótulo de criação. No polling
(GET /api/v1/tasks/:id) a task evolui por pending → processing →
completed (com resultUrl da imagem) ou failed. Ver
Ciclo de vida da task.
Exemplo de erro
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Campo 'model' é obrigatório."
}
}Idempotência
Envie o header Idempotency-Key (opcional, ≤128 chars, TTL 24h). Repetir a mesma chave
retorna a resposta original sem novo débito. A concorrência é limitada a 20
tasks simultâneas por usuário. Ver Idempotência.
Custo
O custo em créditos depende do modelo e da resolução escolhidos. O valor é debitado quando a task é aceita.
Erros relevantes
| Código | HTTP | Quando |
|---|---|---|
VALIDATION_ERROR | 400 | model ausente/desconhecido, prompt ausente, proporção/resolução ou referências inválidas para o modelo, Idempotency-Key acima de 128 caracteres |
INSUFFICIENT_CREDITS | 402 | saldo insuficiente |
FORBIDDEN | 403 | token sem generate:image |
RATE_LIMITED / MAX_CONCURRENT_TASKS | 429 | rate limit ou 20 tasks simultâneas |
INTERNAL_ERROR | 500 | erro interno ao processar a cobrança |
GENERATION_FAILED | 502 | falha do provider |
PROVIDER_UNAVAILABLE | 503 | provider indisponível |