Ir para o conteúdo
Português (Brasil)
Obter chave de API
Guia da API

Autenticação

Ver como Markdown Atualizado

Toda chamada que executa um modelo ou lê suas requisições precisa de uma chave de API. O catálogo (GET /models, GET /categories), POST /quote e o documento OpenAPI são públicos.

Chaves de API

Crie e revogue chaves em https://doitong.com/developers/dashboard#keys. Uma chave se parece com doitong_ seguido por 64 caracteres hexadecimais e é exibida apenas uma vez, quando você a cria. Envie-a no cabeçalho Authorization:

terminal
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"

X-API-Key: <key> também funciona.

Uma requisição sem chave recebe 401 com o código missing_api_key; uma chave desconhecida, revogada ou expirada também recebe 401.

Escopos

Cada chave possui escopos. A API de modelos verifica estes:

Ação Escopo necessário
Executar um modelo, cancelar uma requisição, excluir os arquivos de uma requisição, alterar a configuração de armazenamento models:run (chaves com os escopos antigos images:create ou videos:create também funcionam)
Criar uma URL de upload models:run ou media:upload
Ler requisições, conta models:read (uma chave que pode executar modelos também pode ler)

Novas chaves recebem models:read e models:run por padrão. Uma chamada sem o escopo correto recebe 403 com o código insufficient_scope.

Limites de créditos

Uma chave pode ter seu próprio limite em créditos de API (1.000 créditos de API = $ 1), definido pelo proprietário da conta: um limite total, um limite diário (últimas 24 horas) ou ambos. Antes de uma execução ser cobrada, o custo é comparado ao que a chave já gastou por meio desta API (líquido de reembolsos). Uma execução que ultrapassaria o limite é recusada com 402 budget_exceeded e nada é cobrado.

Uma chave sem limite pode gastar até o saldo de API. Separadamente, uma execução que o saldo de API não puder cobrir recebe 402 insufficient_credits com um top_up_url.

GET https://api.doitong.com/v1/account mostra o saldo de API e o limite restante da chave (ambos em créditos de API):

200 OK · conta
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}

budget_remaining é null quando a chave não tem um limite próprio.

Limites de taxa

Cada chave pode fazer 3600 requisições por hora, a menos que seu limite tenha sido definido de outra forma. Toda resposta autenticada contém o estado atual:

Cabeçalho Significado
X-RateLimit-Limit Requisições permitidas na janela atual
X-RateLimit-Remaining Requisições restantes na janela atual
X-RateLimit-Reset Horário Unix em que a janela é redefinida

Ao ultrapassar o limite, você recebe 429 com um cabeçalho Retry-After (segundos). A consulta contínua com ?wait= conta como uma requisição por chamada, então esperar é mais econômico do que consultar rapidamente.

Também há um limite de 10 requisições em andamento (queued ou running) por conta. Iniciar mais uma retorna 429 too_many_inflight; inicie-a novamente depois que uma terminar.