Skip to main content
Most endpoints take an API key in the xi-api-key header. Account-management endpoints such as /v1/api-keys require a browser session. Create keys on the API keys page, or use breeze login to create a device-specific CLI key.

​
Sending your API key

Breeze accepts the key two ways. Both are equivalent.
  • xi-api-key header
  • Authorization: Bearer <key> header
When both are present, xi-api-key takes precedence.

​
Key lifecycle

  • Each account can keep up to 50 API keys, including disabled and CLI device keys. Delete an unused key to free a slot. Rotating an existing key replaces it without requiring an additional slot.
  • Keys have a stable key_id, prefix, and status.
  • Breeze returns the plaintext api_key only when you create or rotate a key. Store it immediately; it cannot be viewed again.
  • CLI login uses the same hash-only key model. The browser authorizes a short login flow, then the CLI exchanges a local verifier for one plaintext key response and saves it in ~/.breeze.
  • Use key_id for key management, request-log attribution, and support investigations. API-key authenticated responses include x-breeze-api-key-id.
  • Status is active, expiring, or disabled. Disabled keys return 401 AUTH_REQUIRED immediately and can be re-enabled.
  • Delete a key to remove it entirely. Use one key per environment; the last-used timestamp surfaces stale keys.

​
Credit budgets

Each API key can have an optional hard credit limit. The default is Unlimited. A finite limit tracks Used, In flight, and Remaining credits from the key’s last reset. The effective amount available to a request is the lower of the key’s remaining budget and the account’s real credit balance. A key budget does not reserve credits from the account. Resetting usage starts a new key-budget period at zero; it does not refund or add account credits. Setting the limit to 0 blocks paid generation calls while keeping non-billable endpoints available. When a key reaches its limit, paid requests return 402 API_KEY_CREDIT_LIMIT_EXCEEDED and should not be retried without raising or resetting the limit. Rotating a key keeps the old and replacement credentials on the same budget during the 30-day compatibility period. Disabling or enabling a key does not change its budget counters.

​
Inspect the current key

GET /v1/api-keys/current returns the key that authenticated the request, so an integration can confirm a key is still usable before it starts work. It is the one /v1/api-keys endpoint that takes an API key instead of a browser session.
  • credit_limit and credit_remaining are null for keys without a finite budget. Credits use the same decimal values as the key list.
  • The budget is read fresh on every call, so a reset from the Console or a debit that just landed is visible immediately.
  • The endpoint only reports: it never reserves credits, and an exhausted key still answers 200 with credit_remaining at 0. Paid endpoints are where 402 API_KEY_CREDIT_LIMIT_EXCEEDED is returned.
  • A missing, disabled, expired, or deleted key returns 401 AUTH_REQUIRED, as does a browser session.
See Get the current API key in the API reference.

​
Common errors

  • 401 AUTH_REQUIRED: missing, malformed, deleted, or disabled key.
  • 403 FORBIDDEN: valid key with no access to the requested resource.
See the full list on the errors page.

​
Continue from here

SDK quickstart

Create a key, install the SDK, and make your first text-to-speech request.

CLI auth

Use browser login, local profiles, and stdin key entry from the command line.

Manage API keys

List, create, rotate, disable, and delete keys via the session-only /v1/api-keys endpoints.

API reference

Review base URL, content types, generated endpoint docs, and response conventions.

Errors

Handle auth, validation, billing, concurrency, and generation failures.