# Consultar seu saldo com uma chave de API
> Consulte a cota restante da chave atual com uma chave de API sk-: GET /v1/user/balance retorna is_active / balance / unit, e GET /v1/credits retorna total_credits / total_usage no estilo OpenRouter. Compatível com a consulta periódica de clientes de terceiros, como o cc-switch.
URL: https://docs.lmuai.com/pt/docs/api/balance
Com uma chave de API que começa com `sk-` você consulta diretamente **a cota restante e a disponibilidade dessa chave**. Indicado para clientes de terceiros que exibem o saldo na interface, ou para scripts que monitoram o saldo.
**Estes endpoints são somente leitura**: não são cobrados e não consomem cota. A autenticação valida apenas a chave, então você ainda consegue ler a cota restante mesmo quando a cota estiver esgotada e as chamadas de negócio forem rejeitadas (nesse caso `is_active` é `false`).
***
## 1. Visão geral dos endpoints [#1-visão-geral-dos-endpoints]
| Endpoint | Formato de cliente compatível | Retorna |
| ---------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET /v1/user/balance` | Modelo genérico de saldo do cc-switch | `is_active` / `balance` / `unit`, mais `used` / `total` quando a chave tem cota total |
| `GET /user/balance` | Igual ao anterior, para uma Base URL sem `/v1` | Idêntico à linha anterior |
| `GET /v1/credits` | Estilo OpenRouter | `data.total_credits` / `data.total_usage` |
| Item | Valor |
| ------------------- | -------------------------------- |
| Base URL | `https://api.lmuai.com` |
| Autenticação | `Authorization: Bearer ` |
| Formato da resposta | JSON |
| Exige login? | Não, basta a chave de API |
`/user/balance` é um alias de `/v1/user/balance` (usado quando a Base URL do cliente é configurada sem `/v1`). `/v1/credits` **não** tem alias no caminho raiz e deve incluir `/v1`.
***
## 2. Qual saldo é retornado [#2-qual-saldo-é-retornado]
`balance` não é necessariamente o saldo da carteira da conta: é **a cota restante realmente disponível para a chave atual**, resolvida nesta ordem:
| Ordem | Situação da chave | O que `balance` significa |
| ----- | ----------------------------------------- | --------------------------------------------------------------------------------- |
| 1 | A chave tem cota total própria | A cota restante dessa chave (`total - used`) |
| 2 | A chave pertence a um grupo de assinatura | A cota restante da assinatura (`unit` é `requests` quando contada por requisição) |
| 3 | Nenhum dos anteriores | O saldo da carteira da conta |
Além disso, `is_active` indica se a chave **pode ser usada agora para chamadas de negócio**: é `true` quando a chave está ativa, não expirou e sua cota total não está esgotada; também é `false` quando a chave pertence a um grupo de assinatura sem assinatura ativa.
***
## 3. `GET /v1/user/balance` [#3-get-v1userbalance]
```http
GET /v1/user/balance HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```
**Resposta — modo saldo da carteira** (a chave não tem cota e não está em grupo de assinatura):
```json
{
"is_active": true,
"balance": 1575.13,
"unit": "USD"
}
```
**Resposta — a chave tem cota total** (nesse caso `used` e `total` também são retornados):
```json
{
"is_active": true,
"balance": 6,
"unit": "USD",
"used": 4,
"total": 10
}
```
**Resposta — grupo de assinatura contado por requisição**:
```json
{
"is_active": true,
"balance": 842,
"unit": "requests"
}
```
### Campos da resposta [#campos-da-resposta]
| Campo | Tipo | Descrição |
| ----------- | ------ | ------------------------------------------------------------------------------- |
| `is_active` | bool | Se a chave pode ser usada agora para chamadas de negócio |
| `balance` | number | Cota restante; veja `unit` para a unidade |
| `unit` | string | `USD` (padrão), ou `requests` em grupos de assinatura contados por requisição |
| `used` | number | **Presente apenas quando a chave tem cota total**: cota já usada por esta chave |
| `total` | number | **Presente apenas quando a chave tem cota total**: cota total desta chave |
`used` / `total` só têm valores significativos no modo de cota por chave. Os modos saldo da carteira e assinatura não retornam esses campos — use `balance` e não o deduza de `total - used`.
***
## 4. `GET /v1/credits` [#4-get-v1credits]
Formato de saldo estilo OpenRouter; os clientes exibem a cota restante como `total_credits - total_usage`.
```http
GET /v1/credits HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```
**Resposta:**
```json
{
"data": {
"total_credits": 20,
"total_usage": 4
}
}
```
| Campo | Tipo | Descrição |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `data.total_credits` | number | **Usado + restante**, de modo que `total_credits - total_usage` seja exatamente a cota restante |
| `data.total_usage` | number | Cota já usada |
`total_credits` é um valor composto de "usado + restante" — **não** é o limite literal da cota. No modo saldo da carteira, `total_usage` é `0` e `total_credits` equivale ao saldo; quando a cota se esgota, a cota restante é limitada a `0`, portanto nesse caso `total_credits` equivale à quantidade usada.
***
## 5. Configuração em clientes de terceiros [#5-configuração-em-clientes-de-terceiros]
| Cliente / cenário | Como configurar |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Modelo genérico de saldo do cc-switch | A Base URL `https://api.lmuai.com` (sem `/v1`) ou `https://api.lmuai.com/v1` (com `/v1`) funcionam igualmente |
| Clientes compatíveis com OpenRouter (Kelivo, RikkaHub etc.) | Base URL `https://api.lmuai.com/v1`; o cliente solicitará `/v1/credits` |
| Script próprio | Chame diretamente `/v1/user/balance`; os campos são mais fáceis de ler |
```bash
curl -s https://api.lmuai.com/v1/user/balance \
-H "Authorization: Bearer sk-xxxxxxxx"
```
***
## 6. Respostas de erro [#6-respostas-de-erro]
A consulta de saldo usa a autenticação padrão por chave de API do gateway, então os erros vêm no mesmo formato das demais chamadas à API. Quando a requisição não traz chave:
```json
{
"code": "API_KEY_REQUIRED",
"message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}
```
| Código de status | `code` | Cenário |
| ---------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | — | Resposta normal; cota esgotada, chave expirada ou assinatura inexistente também retornam `200`, com `is_active: false` indicando que a chave não pode ser usada |
| `401` | `API_KEY_REQUIRED` | A requisição não traz chave de API |
| `401` | `INVALID_API_KEY` | A chave não existe ou está em formato inválido |
| `401` | `API_KEY_DISABLED` | A chave foi desativada |
| `403` | `ACCESS_DENIED` | A chave tem lista de IPs permitidos / bloqueados e o IP atual não é permitido |
Para erros gerais, consulte [Códigos de erro](/pt/docs/guide/errors).
***
## 7. Diferença em relação a "Exportar detalhes de uso" [#7-diferença-em-relação-a-exportar-detalhes-de-uso]
| | Os endpoints de saldo desta página | [Exportar detalhes de uso](/pt/docs/api/usage-export) |
| ------------- | ---------------------------------------------------- | ----------------------------------------------------- |
| Autenticação | Chave de API `sk-` | Conta e senha trocadas por um JWT |
| Granularidade | Cota restante da chave atual | Detalhes por requisição no nível da conta |
| Caso de uso | Exibir o saldo em um cliente, monitoramento de saldo | Exportação de faturas, conciliação, carga em BI |
`GET /v1/usage` fica entre os dois: também aceita uma chave `sk-` e retorna as estatísticas de uso de hoje e acumuladas, junto com as informações de cota da chave atual, com campos mais detalhados.