# Autenticação

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](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`:

```bash
curl https://api.doitong.ru/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"
```

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

> [!WARNING]
> Mantenha as chaves no seu servidor: qualquer pessoa que tenha uma chave pode gastar os créditos de API que ela tem permissão para gastar. Se uma chave vazar,
> revogue-a e crie uma nova.

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.

> [!IMPORTANT]
> Uma recusa por limite é definitiva: tentar novamente não ajudará até que o proprietário aumente o limite.

 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.ru/v1/account` mostra o saldo de API e o limite restante da chave (ambos em créditos de API):

```json 200 OK · conta
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.ru/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.