# Schlüssel, Tarif und Guthaben

> Was ein OpenCheese-API-Schlüssel noch ausgeben kann: GET /v1/key, /v1/plan und /v1/balance mit ihren Antwortfeldern. Kostenlos, ohne Anrechnung auf Limits.
>
> Webseite: https://opencheese.dev/de/docs/account/ · Alle Seiten der Doku: https://opencheese.dev/de/docs.md

Drei rein lesende Endpunkte zeigen, was ein Schlüssel noch ausgeben kann. Sie verwenden denselben
Schlüssel wie jede andere Anfrage, kosten nichts und werden nicht auf deine Anfragelimits
angerechnet.

Jede Antwort ist in `data` verpackt, und alle Beträge sind in Credits (USD) angegeben. `null` bedeutet,
dass es kein Limit gibt oder dass ein Fenster noch nicht begonnen hat.

## Der Schlüssel: GET /v1/key

```bash
curl https://api.opencheese.dev/v1/key \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

```json
{
  "data": {
    "label": "Laptop",
    "limit": 50,
    "limit_usage": 12.5,
    "limit_remaining": 37.5,
    "limit_reset": null,
    "usage": 182.4,
    "created_at": "2026-09-01T10:00:00.000Z",
    "last_used_at": "2026-10-17T09:12:00.000Z"
  }
}
```

- `limit` ist das Ausgabenlimit des Schlüssels. Es begrenzt, was der Schlüssel von deinem
  Guthaben ausgibt; Tarifverbrauch zählt nie dazu und wird nie dadurch blockiert.
- `limit_usage` sind die Guthabenausgaben, die seit dem letzten Zurücksetzen auf der Seite
  **API-Schlüssel** auf das Limit angerechnet wurden, und `limit_remaining` ist der Rest. Limits
  setzen sich nie von selbst zurück, deshalb ist `limit_reset` immer `null`.
- `usage` ist alles, was der Schlüssel je ausgegeben hat, aus deinem Tarif und deinem Guthaben.

## Der Tarif: GET /v1/plan

```bash
curl https://api.opencheese.dev/v1/plan \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

Ohne Tarif lautet die Antwort `{"data": null}`. Mit Tarif:

```json
{
  "data": {
    "name": "Pro",
    "status": "active",
    "started_at": "2026-10-01T09:00:00.000Z",
    "expires_at": "2026-10-31T09:00:00.000Z",
    "auto_renew": true,
    "windows": {
      "five_hour": { "limit": 5, "usage": 1.2, "remaining": 3.8, "resets_at": "2026-10-17T14:00:00.000Z" },
      "weekly": { "limit": 25, "usage": 9.1, "remaining": 15.9, "resets_at": "2026-10-20T09:00:00.000Z" },
      "monthly": { "limit": 100, "usage": 40, "remaining": 60, "resets_at": "2026-10-31T09:00:00.000Z" }
    },
    "options": {
      "balance_allowed": true,
      "use_balance_on_limit": true,
      "use_balance_for_other_models": false
    }
  }
}
```

- Das 5-Stunden-Fenster beginnt mit deiner ersten abgerechneten Anfrage, deshalb ist sein
  `resets_at` bis dahin `null`. Das Monatsfenster erneuert sich zum Zeitpunkt `expires_at`.
- `balance_allowed` gibt an, ob der Tarif überhaupt auf dein Guthaben zugreifen darf.
  `use_balance_on_limit` lässt den Tarif mit deinem Guthaben weiterlaufen, sobald ein Fenster
  aufgebraucht ist, und `use_balance_for_other_models` bezahlt Modelle außerhalb des Tarifs aus
  deinem Guthaben. Beide sind Schalter in der **Übersicht** des Dashboards und melden `false`,
  wenn der Tarif keine Guthabennutzung erlaubt.

## Das Guthaben: GET /v1/balance

```bash
curl https://api.opencheese.dev/v1/balance \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

Der Endpunkt meldet dein Guthaben und den Verbrauch im laufenden Kalendermonat (UTC), Tarif- und
Guthabenabbuchungen zusammengerechnet:

```json
{
  "data": {
    "balance": 12.34,
    "month": "2026-10",
    "monthly_usage": { "tokens": 1234567, "credits": 8.9, "requests": 312 },
    "monthly_limits": { "tokens": null, "credits": null }
  }
}
```

`monthly_limits` sind Kontolimits, die ein Administrator setzen kann; `null` bedeutet, dass keines
gesetzt ist.

## Vor einer langen Aufgabe prüfen

```bash
curl -s https://api.opencheese.dev/v1/balance \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" | jq '.data.balance'
```

Ist das Guthaben aufgebraucht oder ein Zeitfenster des Tarifs ausgeschöpft, ohne dass der Tarif
mit deinem Guthaben weiterläuft (`use_balance_on_limit`), werden Anfragen mit
`plan_limit_reached` abgelehnt; siehe [Fehler und Ratenlimits](https://opencheese.dev/de/docs/errors.md).