# Guthaben mit einem API-Schlüssel abfragen
> Fragen Sie das verbleibende Kontingent des aktuellen Schlüssels mit einem sk- API-Schlüssel ab: GET /v1/user/balance liefert is_active / balance / unit, GET /v1/credits liefert total_credits / total_usage im OpenRouter-Stil. Kompatibel mit dem Abfragezyklus von Drittanbieter-Clients wie cc-switch.
URL: https://docs.lmuai.com/de/docs/api/balance
Mit einem API-Schlüssel, der mit `sk-` beginnt, fragen Sie direkt **das verbleibende Kontingent und die Verfügbarkeit dieses Schlüssels** ab. Gedacht für Drittanbieter-Clients, die ein Guthaben in der Oberfläche anzeigen, oder für Skripte, die das Guthaben überwachen.
**Diese Endpunkte sind nur lesend**: Sie werden nicht abgerechnet und verbrauchen kein Kontingent. Die Authentifizierung prüft nur den Schlüssel selbst, daher können Sie das verbleibende Kontingent auch dann noch lesen, wenn es aufgebraucht ist und Geschäftsaufrufe abgelehnt würden (in diesem Fall ist `is_active` `false`).
***
## 1. Endpunktübersicht [#1-endpunktübersicht]
| Endpunkt | Passendes Client-Format | Liefert |
| ---------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `GET /v1/user/balance` | Generische Guthaben-Vorlage von cc-switch | `is_active` / `balance` / `unit`, plus `used` / `total`, wenn der Schlüssel ein Gesamtkontingent hat |
| `GET /user/balance` | Wie oben, für eine Base URL ohne `/v1` | Identisch mit der Zeile darüber |
| `GET /v1/credits` | OpenRouter-Stil | `data.total_credits` / `data.total_usage` |
| Element | Wert |
| ---------------------- | -------------------------------- |
| Base URL | `https://api.lmuai.com` |
| Authentifizierung | `Authorization: Bearer ` |
| Antwortformat | JSON |
| Anmeldung erforderlich | Nein, der API-Schlüssel genügt |
`/user/balance` ist ein Alias von `/v1/user/balance` (wird verwendet, wenn die Base URL des Clients ohne `/v1` konfiguriert ist). `/v1/credits` hat **keinen** Alias im Wurzelpfad und muss `/v1` enthalten.
***
## 2. Welches Guthaben zurückgegeben wird [#2-welches-guthaben-zurückgegeben-wird]
`balance` ist nicht zwangsläufig das Wallet-Guthaben des Kontos, sondern **das verbleibende Kontingent, das dem aktuellen Schlüssel tatsächlich zur Verfügung steht**, ermittelt in dieser Reihenfolge:
| Reihenfolge | Situation des Schlüssels | Bedeutung von `balance` |
| ----------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 1 | Der Schlüssel hat ein eigenes Gesamtkontingent | Das verbleibende Kontingent dieses Schlüssels (`total - used`) |
| 2 | Der Schlüssel gehört zu einer Abonnementgruppe | Das verbleibende Kontingent des Abonnements (`unit` ist `requests`, wenn pro Anfrage gezählt wird) |
| 3 | Nichts davon zutreffend | Das Wallet-Guthaben des Kontos |
Zusätzlich gibt `is_active` an, ob der Schlüssel **aktuell für Geschäftsaufrufe genutzt werden kann**: `true`, wenn der Schlüssel aktiv, nicht abgelaufen und sein Gesamtkontingent nicht aufgebraucht ist; ebenfalls `false`, wenn der Schlüssel zu einer Abonnementgruppe ohne aktives Abonnement gehört.
***
## 3. `GET /v1/user/balance` [#3-get-v1userbalance]
```http
GET /v1/user/balance HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```
**Antwort — Modus Wallet-Guthaben** (der Schlüssel hat kein Kontingent und gehört keiner Abonnementgruppe an):
```json
{
"is_active": true,
"balance": 1575.13,
"unit": "USD"
}
```
**Antwort — der Schlüssel hat ein Gesamtkontingent** (in diesem Fall werden zusätzlich `used` und `total` zurückgegeben):
```json
{
"is_active": true,
"balance": 6,
"unit": "USD",
"used": 4,
"total": 10
}
```
**Antwort — Abonnementgruppe, pro Anfrage gezählt**:
```json
{
"is_active": true,
"balance": 842,
"unit": "requests"
}
```
### Antwortfelder [#antwortfelder]
| Feld | Typ | Beschreibung |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `is_active` | bool | Ob der Schlüssel aktuell für Geschäftsaufrufe genutzt werden kann |
| `balance` | number | Verbleibendes Kontingent; Einheit siehe `unit` |
| `unit` | string | `USD` (Standard) oder `requests` bei Abonnementgruppen, die pro Anfrage zählen |
| `used` | number | **Nur vorhanden, wenn der Schlüssel ein Gesamtkontingent hat**: bereits verbrauchtes Kontingent dieses Schlüssels |
| `total` | number | **Nur vorhanden, wenn der Schlüssel ein Gesamtkontingent hat**: Gesamtkontingent dieses Schlüssels |
`used` / `total` haben nur im Modus „Kontingent pro Schlüssel“ aussagekräftige Werte. Die Modi Wallet-Guthaben und Abonnement geben diese Felder nicht zurück – verwenden Sie `balance` und leiten Sie es nicht aus `total - used` ab.
***
## 4. `GET /v1/credits` [#4-get-v1credits]
Guthabenformat im OpenRouter-Stil; Clients zeigen das verbleibende Kontingent als `total_credits - total_usage` an.
```http
GET /v1/credits HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```
**Antwort:**
```json
{
"data": {
"total_credits": 20,
"total_usage": 4
}
}
```
| Feld | Typ | Beschreibung |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `data.total_credits` | number | **Verbraucht + verbleibend**, sodass `total_credits - total_usage` genau dem verbleibenden Kontingent entspricht |
| `data.total_usage` | number | Bereits verbrauchtes Kontingent |
`total_credits` ist ein zusammengesetzter Wert aus „verbraucht + verbleibend“ und **nicht** der wörtliche Wert der Kontingent-Obergrenze. Im Modus Wallet-Guthaben ist `total_usage` `0` und `total_credits` entspricht dem Guthaben; ist das Kontingent aufgebraucht, wird das verbleibende Kontingent auf `0` begrenzt, sodass `total_credits` dann der verbrauchten Menge entspricht.
***
## 5. Einrichtung in Drittanbieter-Clients [#5-einrichtung-in-drittanbieter-clients]
| Client / Szenario | Einrichtung |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Generische Guthaben-Vorlage von cc-switch | Base URL `https://api.lmuai.com` (ohne `/v1`) oder `https://api.lmuai.com/v1` (mit `/v1`) funktionieren beide |
| OpenRouter-kompatible Clients (Kelivo, RikkaHub usw.) | Base URL `https://api.lmuai.com/v1`; der Client ruft `/v1/credits` auf |
| Eigenes Skript | Rufen Sie direkt `/v1/user/balance` auf; die Felder sind leichter zu lesen |
```bash
curl -s https://api.lmuai.com/v1/user/balance \
-H "Authorization: Bearer sk-xxxxxxxx"
```
***
## 6. Fehlerantworten [#6-fehlerantworten]
Die Saldoabfrage nutzt die standardmäßige API-Schlüssel-Authentifizierung des Gateways, daher kommen Fehler im selben Format wie bei anderen API-Aufrufen. Wenn die Anfrage keinen Schlüssel enthält:
```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"
}
```
| Statuscode | `code` | Szenario |
| ---------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | — | Normale Antwort; ein aufgebrauchtes Kontingent, ein abgelaufener Schlüssel oder ein fehlendes Abonnement liefern ebenfalls `200`, mit `is_active: false` als Zeichen, dass der Schlüssel nicht nutzbar ist |
| `401` | `API_KEY_REQUIRED` | Die Anfrage enthält keinen API-Schlüssel |
| `401` | `INVALID_API_KEY` | Der Schlüssel existiert nicht oder ist falsch formatiert |
| `401` | `API_KEY_DISABLED` | Der Schlüssel wurde deaktiviert |
| `403` | `ACCESS_DENIED` | Für den Schlüssel ist eine IP-Zulassungs- / Sperrliste gesetzt und die aktuelle IP ist nicht zugelassen |
Allgemeine Fehler finden Sie unter [Fehlercodes](/de/docs/guide/errors).
***
## 7. Unterschied zu „Nutzungsdetails exportieren“ [#7-unterschied-zu-nutzungsdetails-exportieren]
| | Die Guthaben-Endpunkte dieser Seite | [Nutzungsdetails exportieren](/de/docs/api/usage-export) |
| ----------------- | ------------------------------------------------------ | -------------------------------------------------------- |
| Authentifizierung | `sk-` API-Schlüssel | Konto und Passwort gegen ein JWT |
| Granularität | Verbleibendes Kontingent des aktuellen Schlüssels | Details pro Anfrage auf Kontoebene |
| Anwendungsfall | Guthaben in einem Client anzeigen, Guthabenüberwachung | Rechnungsexport, Abgleich, Laden in ein BI |
`GET /v1/usage` liegt dazwischen: Es akzeptiert ebenfalls einen `sk-`-Schlüssel und liefert die heutigen und kumulierten Nutzungsstatistiken sowie die Kontingentinformationen des aktuellen Schlüssels – mit detaillierteren Feldern.