Documentação da APIAutenticação e idempotência
Chaves de API, escopos, IDs de requisição e retentativas seguras
Autenticação bearer
Crie e revogue chaves em Configurações → Chaves de API. O segredo aparece uma única vez. Envie-o no cabeçalho padrão:
Authorization: Bearer sd_YOUR_KEYSomente o cabeçalho Authorization é aceito. Credenciais na query string e
X-API-Key não são suportadas. Uma chave ausente, inválida, expirada ou revogada
retorna 401 UNAUTHORIZED. Uma chave válida sem o escopo do endpoint retorna
403 FORBIDDEN.
Escopos
| Escopo | Permite |
|---|---|
images:generate | criar jobs de geração |
images:edit | criar jobs de edição |
images:convert | criar jobs de conversão |
jobs:read | ler jobs da mesma conta |
credits:read | ler o saldo atual |
Use chaves restritas separadas por aplicação e por ambiente. Revogar uma chave não afeta jobs já criados na conta.
Idempotência
Os três endpoints POST exigem um Idempotency-Key com 8 a 255 caracteres.
Repetir o mesmo endpoint com a mesma chave e a mesma requisição canônica retorna
o job original, sem reservar créditos de novo. Reutilizar a chave com conteúdo
diferente retorna 409 IDEMPOTENCY_CONFLICT.
Em requisições multipart, os bytes da imagem de origem fazem parte da identidade. Trocar a imagem enviada mantendo a chave é, portanto, um conflito.
IDs de requisição
Toda resposta inclui X-Request-Id. Os corpos de erro o repetem em
error.request_id. Esses IDs podem ser guardados com segurança nos logs da
aplicação.