Consumo e cobrança

O consumo por requisição vem em toda resposta — você pode faturar com base nele com segurança. O saldo atual pode ser consultado em GET /v1/dashboard/balance.

Consumo por requisição

Toda resposta de /v1/messages inclui um objeto usage com a contagem de tokens:

{
"usage": {
"input_tokens": 48,
"output_tokens": 92,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}

No chat-completions , os mesmos números aparecem como prompt_tokens, completion_tokens e total_tokens.

Saldo da chave: GET /v1/dashboard/balance

Retorna o saldo atual da chave. Responde na hora e aceita a mesma chave da API.

curl -H "Authorization: Bearer sk-YOUR_KEY_HERE" \
https://api.oneprovider.dev/v1/dashboard/balance

Resposta 200 OK:

{
"object": "balance",
"balance_usd": 54.77,
"expires_at": "2026-07-29T19:00:00Z",
"is_active": true,
"last_synced_at": "2026-06-29T19:52:00Z"
}

• balance_usd: o saldo disponível da chave, em USD.
• expires_at: a expiração da chave (ISO 8601 em UTC, null se não houver).
• is_active: false se a chave estiver pausada ou desativada.
• last_synced_at: quando o saldo foi atualizado pela última vez.

Endpoints de saldo compatíveis com a OpenAI

Apps como NextChat e LobeChat leem o saldo em caminhos no estilo OpenAI. Eles funcionam com a mesma chave em Authorization: Bearer:

Erros: 401 para um cabeçalho Authorization: Bearer ausente ou inválido; 429 quando você excede o limite de requisições (os endpoints de saldo são limitados por IP). O saldo e o gasto por requisição também estão no painel (a página “Consumo” no bot @oneprovider_robot e em app.oneprovider.dev ).

Taxas efetivas

Cobramos um valor fixo por 1M de tokens, conforme a taxa publicada em /pricing . Não há multiplicador, mínimo nem arredondamento. A conta é:

cost = (input_tokens / 1_000_000) * rate_in
+ (output_tokens / 1_000_000) * rate_out
+ (cache_read_input_tokens / 1_000_000) * (rate_in * 0.10)
+ (cache_creation_input_tokens / 1_000_000) * (rate_in * 1.25)

• As leituras de cache são cobradas a 10% da taxa de entrada na maioria dos modelos.
• A criação de cache (a primeira vez que um ponto de cache é gravado) é cobrada a 125% da taxa de entrada na maioria dos modelos.
• Os multiplicadores 0,10 e 1,25 da fórmula são típicos: as taxas exatas de leitura e gravação em cache de cada modelo estão na tabela de modelos .

Quando o saldo acaba

Quando o saldo da chave chega a zero, as requisições com ela retornam 429 com error.type insufficient_balance, error.code insufficient_quota e o cabeçalho x-should-retry: false:

HTTP/1.1 429 Too Many Requests
x-should-retry: false
Content-Type: application/json
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}

Não tente de novo: confira o saldo do painel e o limite da chave (a página “Chaves”), recarregue o painel se precisar e envie a requisição outra vez (como ). Todos os outros códigos estão em Códigos de erro .

Rate-limit (429)

Requisições demais em pouco tempo retornam 429 rate_limit_error. A resposta pode trazer um cabeçalho Retry-After em segundos:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded; retry later"
}
}

Quando Retry-After estiver presente, aguarde pelo menos esse tempo; caso contrário, tente de novo com uma pausa crescente. Se os 429 continuarem, reduza a concorrência no cliente. Requisições barradas pelo limite não consomem saldo.

Precisão do consumo por requisição

Os objetos usage por requisição somam exatamente o gasto real por chave. Verificado em 08/05/2026 numa amostra de 24 h com 25.845 requisições: o desvio máximo foi inferior a US$ 0,001 (arredondamento na 6ª casa decimal). Você pode faturar com segurança com base no usage de cada requisição.