API Avatrix v1

Esta documentação detalha os endpoints disponíveis na API REST v1 da Avatrix. Esta API foi desenhada para integrações externas (back-end a back-end), não para o navegador — por isso não envia CORS.

Base URL

Todas as rotas vivem sob a URL base:

https://avatrix.io/api/v1

Autenticação

A maioria dos endpoints exige um token no header Authorization. Crie um token no painel em /account/tokens e o envie em cada requisição:

curl https://avatrix.io/api/v1/profile \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx"

O token tem o formato av_<64 hex> e é exibido uma única vez na criação. Ver Autenticação e Escopos.

Quickstart — gerar uma imagem

curl -X POST https://avatrix.io/api/v1/generate/image \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "model": "nano-banana-pro", "prompt": "uma influencer numa cafeteria, luz natural" }'

A resposta é 202 Accepted com um taskId. A geração é assíncrona — acompanhe o resultado por polling em GET /api/v1/tasks/:id ou receba um webhook quando a task concluir:

{ "success": true, "data": { "taskId": "...", "status": "queued" } }

Envelope de resposta

Toda resposta segue o mesmo envelope:

{ "success": true,  "data": { "...": "..." } }
{ "success": false, "error": { "code": "UNAUTHORIZED", "message": "..." } }

Veja a lista completa de códigos em Erros.

Como navegar

• Conceitos — autenticação, escopos, paginação, idempotência, rate limit, ciclo de vida da task, webhooks e erros.
• Endpoints — agrupados por categoria (Leitura, Geração de imagem, vídeo e áudio e Pagamentos), cada um com body, exemplos e erros.