Conceitos

Idempotência

Use o header Idempotency-Key para repetir requisições com segurança, sem duplicar gerações nem cobranças.

Operações que criam algo — gerações e cobranças — aceitam o header Idempotency-Key. Ele garante que, se você reenviar a mesma requisição (timeout de rede, retry automático), ela seja processada uma única vez.

O header permanece opcional para compatibilidade com clientes v1 existentes. Sem ele, cada chamada é uma operação independente: um retry pode criar outra task e gerar outro débito. Por isso, envie a chave em toda operação cobrada.

Como funciona

Envie um Idempotency-Key único por operação (≤128 caracteres).
A chave vale por 24 horas (TTL).
Repetir a mesma chave retorna a resposta original — o mesmo taskId (ou a mesma order) — sem novo débito de créditos e sem criar uma segunda task/cobrança.
Duas chamadas concorrentes com a mesma chave reservam uma única operação; a segunda recebe 409 REQUEST_IN_PROGRESS enquanto a primeira ainda não tem uma resposta persistida.
Reutilizar a chave com outro body retorna 409 IDEMPOTENCY_CONFLICT.

Onde se aplica

Tipo de endpoint	Rotas
Geração	`POST /api/v1/generate/*` (image, video, voice, …)
Pagamento	`POST /api/v1/credits`, `POST /api/v1/subscriptions`

Exemplo de uso

cURL

curl -X POST https://avatrix.io/api/v1/generate/voice \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-tts-001" \
  -d '{ "text": "Olá!", "voice": "sarah" }'

Reenviar a requisição acima com Idempotency-Key: 9f1c-tts-001 dentro de 24h devolve o mesmo taskId, sem gerar uma nova task nem debitar créditos de novo.

Concorrência

Independente da idempotência, há um limite de 20 tasks simultâneas por usuário. Ao tentar criar a 21ª task em andamento, a resposta é 429 MAX_CONCURRENT_TASKS. Aguarde tasks em curso concluírem antes de enviar novas. Ver Rate limit & concorrência.