Avançar para o conteúdo
Português (Portugal)
Obter chave de API
Guia da API

Autenticação

Ver como Markdown Atualizado

Todas as chamadas que executam um modelo ou leem os seus pedidos precisam 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 tem o formato doitong_ seguido de 64 caracteres hexadecimais e é apresentada apenas uma vez, quando 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.

Um pedido sem chave recebe 401 com o código missing_api_key; uma chave desconhecida, revogada ou expirada também recebe 401.

Âmbitos

Cada chave tem âmbitos. A API de modelos verifica estes:

Ação Âmbito necessário
Executar um modelo, cancelar um pedido, eliminar os ficheiros de um pedido, alterar a definição de armazenamento models:run (as chaves com os antigos images:create ou videos:create também funcionam)
Criar um URL de carregamento models:run ou media:upload
Ler pedidos e a conta models:read (uma chave que possa executar modelos também pode ler)

As novas chaves recebem models:read e models:run por predefinição. Uma chamada sem o âmbito correto recebe 403 com o código insufficient_scope.

Orçamentos de créditos

Uma chave pode ter o seu próprio orçamento em créditos de API (1000 créditos da API = 1 $), definido pelo titular da conta: um orçamento total, um orçamento diário (últimas 24 horas) ou ambos. Antes de cobrar uma execução, o custo é comparado com o que a chave já gastou através desta API (líquido de reembolsos). Uma execução que o excedesse é recusada com 402 budget_exceeded e não é cobrado qualquer valor.

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

GET https://api.doitong.com/v1/account apresenta o saldo de API e o orçamento 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 orçamento próprio.

Limites de frequência

Cada chave pode fazer 3600 pedidos por hora, salvo se o seu limite tiver sido definido de forma diferente. Todas as respostas autenticadas incluem o estado atual:

Cabeçalho Significado
X-RateLimit-Limit Pedidos permitidos na janela atual
X-RateLimit-Remaining Pedidos restantes na janela atual
X-RateLimit-Reset Hora Unix em que a janela é reposta

Quando ultrapassa o limite, recebe 429 com um cabeçalho Retry-After (segundos). A consulta prolongada com ?wait= conta como um pedido por chamada, pelo que esperar é mais económico do que consultar rapidamente.

Existe também um limite de 10 pedidos em curso (queued ou running) por conta. Iniciar mais um devolve 429 too_many_inflight; inicie-o novamente depois de um terminar.