Docs

API reference

The Bearer Club API follows the OpenAI API format, so official OpenAI SDKs and most OpenAI-compatible tools work unchanged. Unknown request fields pass through to the model where it supports them.

Base URL and authentication

Base URL: https://api.bearer.club/v1 (also served at https://bearer.club/v1)
Auth: Authorization: Bearer <your key> on every request

Keys start with a prefix like the example below. Each key carries its own data policy (Private or Research Share), which you set in your dashboard. Nothing in the request body changes it.

Example header (not a real key)

Authorization: Bearer bc_live_xxxxxxxxxxxx

Every response carries these headers:

Response headers
Header	What it holds
`x-bearer-club-request-id`	Request id. Include it when you contact support.
`x-bearer-club-cost-usd`	What this request cost you, in USD (non-streaming responses).
`x-bearer-club-list-cost-usd`	The same request at the provider's list price, for comparison.
`x-ratelimit-limit-requests`, `x-ratelimit-remaining-requests`, `x-ratelimit-reset-requests`	Per-key request rate limit for your tier.

GET /v1/models

Lists every model you can call, in the OpenAI list format. It works without a key, and every id in the list works with your key as the model of a chat request.

bash

curl https://api.bearer.club/v1/models

Response (one entry shown)

{  "object": "list",  "data": [    {      "id": "deepseek/deepseek-v4-flash",      "object": "model",      "owned_by": "deepseek",      "created": 1792022400,      "name": "DeepSeek V4 Flash 0423",      "kind": "chat",      "model_class": "open",      "context_window": 1048576,      "guest_available": true,      "pricing": {        "currency": "USD",        "list_input_per_1m": 0.091,        "list_output_per_1m": 0.182,        "price_per_image": null,        "price_is_example": false      }    }  ]}

The prices are the provider list prices in USD per 1M tokens. What your key pays depends on your plan and the key's data mode; see Models in the console.

POST /v1/chat/completions

Chat completions in the OpenAI format: model, messages, and optional fields like max_tokens, temperature, tools, tool_choice and response_format. Tool calls and JSON mode pass through where the model supports them.

curl https://api.bearer.club/v1/chat/completions \  -H "Authorization: Bearer $BEARER_CLUB_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "deepseek/deepseek-v4-flash",    "messages": [{"role": "user", "content": "Hello from the Club!"}]  }'

import osfrom openai import OpenAIclient = OpenAI(    base_url="https://api.bearer.club/v1",    api_key=os.environ["BEARER_CLUB_API_KEY"],  # your membership card)resp = client.chat.completions.create(    model="deepseek/deepseek-v4-flash",    messages=[{"role": "user", "content": "Hello from the Club!"}],)print(resp.choices[0].message.content)

import OpenAI from "openai";const client = new OpenAI({  baseURL: "https://api.bearer.club/v1",  apiKey: process.env.BEARER_CLUB_API_KEY, // your membership card});const resp = await client.chat.completions.create({  model: "deepseek/deepseek-v4-flash",  messages: [{ role: "user", content: "Hello from the Club!" }],});console.log(resp.choices[0].message.content);

Streaming

Send "stream": true to receive server-sent events. Each event is a chat.completion.chunk, and the stream ends with data: [DONE]. Add "stream_options": {"include_usage": true} to get token usage in the final chunk.

bash

curl https://api.bearer.club/v1/chat/completions \  -H "Authorization: Bearer $BEARER_CLUB_API_KEY" \  -H "Content-Type: application/json" \  -N \  -d '{    "model": "deepseek/deepseek-v4-flash",    "messages": [{"role": "user", "content": "Count to three."}],    "stream": true,    "stream_options": {"include_usage": true}  }'

text

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"delta":{"content":"One"}}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"delta":{"content":", two, three."}}]}

data: [DONE]

Spend caps are checked before a request is forwarded. A stream that has started is never cut off for spend reasons.

POST /v1/embeddings

Embeddings for models whose kind is embedding (see kind in GET /v1/models). Sending a chat model here returns 400 unsupported_endpoint.

curl https://api.bearer.club/v1/embeddings \  -H "Authorization: Bearer $BEARER_CLUB_API_KEY" \  -H "Content-Type: application/json" \  -d '{"model": "provider/embedding-model-id", "input": "Hello from the Club!"}'

import osfrom openai import OpenAIclient = OpenAI(base_url="https://api.bearer.club/v1", api_key=os.environ["BEARER_CLUB_API_KEY"])emb = client.embeddings.create(model="provider/embedding-model-id", input="Hello from the Club!")print(len(emb.data[0].embedding))

import OpenAI from "openai";const client = new OpenAI({ baseURL: "https://api.bearer.club/v1", apiKey: process.env.BEARER_CLUB_API_KEY });const emb = await client.embeddings.create({ model: "provider/embedding-model-id", input: "Hello from the Club!" });console.log(emb.data[0].embedding.length);

Replace provider/embedding-model-id with an embedding model id from GET /v1/models.

POST /v1/images/generations

Image generation for models whose kind is image. Fields follow the OpenAI format: model, prompt, and optional n and size. Image models are priced per image where the catalog sets a per-image price, otherwise by tokens.

curl https://api.bearer.club/v1/images/generations \  -H "Authorization: Bearer $BEARER_CLUB_API_KEY" \  -H "Content-Type: application/json" \  -d '{"model": "provider/image-model-id", "prompt": "A polar bear pushing a shopping cart", "n": 1}'

import osfrom openai import OpenAIclient = OpenAI(base_url="https://api.bearer.club/v1", api_key=os.environ["BEARER_CLUB_API_KEY"])img = client.images.generate(model="provider/image-model-id", prompt="A polar bear pushing a shopping cart")print(img.data[0])

import OpenAI from "openai";const client = new OpenAI({ baseURL: "https://api.bearer.club/v1", apiKey: process.env.BEARER_CLUB_API_KEY });const img = await client.images.generate({ model: "provider/image-model-id", prompt: "A polar bear pushing a shopping cart" });console.log(img.data[0]);

Errors

Errors use the OpenAI shape. type is the machine-readable reason; code usually repeats it; param names the offending field when there is one. Some errors add an upgrade_url.

403 guest_spend_cap_reached

{  "error": {    "type": "guest_spend_cap_reached",    "message": "Guest usage is capped at $10,000 per calendar year. Upgrade to Member to continue.",    "code": "guest_spend_cap_reached",    "param": null,    "upgrade_url": "https://bearer.club/join?tier=member"  }}

Error types by HTTP status
Status	type	Meaning
400	`invalid_request_error`	Bad JSON, a missing or invalid field, or a model used with the wrong endpoint (`code: unsupported_endpoint`). If the model itself rejects the input, `code` is `upstream_rejected`.
401	`missing_api_key`, `invalid_api_key`	No `Authorization: Bearer` header, or the key is wrong or revoked.
402	`insufficient_credits`, `payment_past_due`, `payment_method_required`	Top up prepaid credits or fix billing in your dashboard.
403	`model_not_in_tier`	The model isn't offered on your tier with this key's data policy (for example, closed models on Guest).
403	`guest_data_consent_required`	Guest keys need the Research Share consent on your account.
403	`guest_spend_cap_reached`	Guest usage is capped at $10,000 per calendar year. Upgrade to Member or wait for the yearly reset.
404	`model_not_found`	Unknown or disabled model id. Check `GET /v1/models`.
413	`invalid_request_error`	Request body too large (`code: body_too_large`).
429	`rate_limit_exceeded`	Too many requests for this key. Wait for the `retry-after` header.
429	`key_spend_cap_reached`	This key hit the monthly spend cap you set. Raise it in your dashboard or wait for the monthly reset.
429	`upstream_rate_limited`	The model is busy. Retry with backoff.
500	`server_error`	Something went wrong on our side. Retry with backoff.
502	`upstream_error`	Upstream issue. Retry with backoff.
503	`model_unavailable`	The model is temporarily unavailable.
504	`upstream_timeout`	The model took too long to respond. Retry with backoff.

Retries

Retry 429 and 5xx responses with exponential backoff. Don't retry 400, 401, 402, 403 or 404 without changing the request.

Limits

Per-key request rate limits depend on your tier and are reported in the x-ratelimit-* headers.
Guest usage is capped at $10,000 per calendar year.
You can set a monthly spend cap on each key in your dashboard.

See Pricing for tiers, and how models are hosted for what sits behind each model id.