> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velobase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI-Compatible Gateway

> Point your OpenAI or Anthropic SDK at Velobase and bill every model call to an end-customer wallet.

Velobase is a model-agnostic, OpenAI-compatible AI gateway. Point your OpenAI
SDK at it and call any available model (Claude, DeepSeek, and more) by its id,
changing two things: the **base URL** and one **header** that says which
end-customer to bill. Every call is metered against that customer's wallet, and
the per-call cost comes back on the response headers.

<Note>
  **Base URL:** `https://api.velobase.io/v1`, the OpenAI SDK expects the `/v1`
  suffix. **Auth:** `Authorization: Bearer <project-key>` (a `vb_live_…` key). A
  project key bills the customer named in the header. You can also issue a
  customer-scoped `vb_customer_…` key that carries its own customer, so no header
  is needed. **Who to bill:** the `X-Velobase-Customer: <your-user-id>` header.
</Note>

## Available models

Call any of these by its `model` id through the OpenAI-compatible endpoint.
Prices are what your customer's wallet is charged, per million tokens.

| `model`                       | Streaming | Input (\$/1M) | Output (\$/1M) |
| ----------------------------- | --------- | ------------- | -------------- |
| `deepseek/deepseek-v4-pro`    | Yes       | \$0.49        | \$0.96         |
| `anthropic/claude-haiku-4.5`  | No        | \$1.10        | \$5.50         |
| `anthropic/claude-sonnet-4.6` | No        | \$3.30        | \$16.50        |
| `anthropic/claude-opus-4.5`   | No        | \$5.50        | \$27.50        |
| `anthropic/claude-opus-4.6`   | No        | \$5.50        | \$27.50        |
| `anthropic/claude-opus-4.7`   | No        | \$5.50        | \$27.50        |
| `anthropic/claude-opus-4.8`   | No        | \$5.50        | \$27.50        |

Call `GET /v1/models` for the live list your project can route. More models open
up as upstreams are connected. Claude models route through Bedrock and are
non-streaming for now, so pick a DeepSeek model when you need streaming.

## Copy for AI

Paste this into your AI coding assistant (Cursor, Claude Code, etc.) and it can
wire up the integration in one shot:

```text theme={null}
You are integrating Velobase into my app. Use the details below; keep my
existing OpenAI/Anthropic code and just change the base URL and add one header.

What it is: an OpenAI-compatible AI gateway that meters and bills every LLM call
against MY end-customers' wallets (per-customer balance, ledger, rate limits).

Setup:
- Base URL: https://api.velobase.io/v1   (the OpenAI SDK needs the /v1 suffix)
- Auth: Authorization: Bearer <VELOBASE_PROJECT_KEY>   (vb_live_...)
- Bill a customer by sending header X-Velobase-Customer: <your-user-id>

Call (Python):
from openai import OpenAI
client = OpenAI(api_key="vb_live_...", base_url="https://api.velobase.io/v1",
                default_headers={"X-Velobase-Customer": "user_123"})
r = client.chat.completions.with_raw_response.create(
    model="anthropic/claude-opus-4.8",
    messages=[{"role": "user", "content": "Hello"}], max_tokens=256)
# billing on headers: x-velobase-cost-cents / -cost-credits /
#                     -balance-credits / -transaction-id
print(r.parse().choices[0].message.content)

Fund a customer first (else 402): POST /v1/customers/{id}/deposit {"amount_usd": 5}
Reconcile: GET /v1/usage (rows carry cost_cents, tokens, transaction_id)
Notes: Claude routes via Bedrock which does not support streaming yet, use
stream=false for Claude (DeepSeek models support streaming). Official models
debit both the customer wallet and your project wallet; a call 402s if either
is empty. Control-plane SDKs: pip install "velobase-billing>=0.2.1" / npm i @velobaseai/billing@^1.1.1.
```

## Make a call

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="vb_live_your_project_key",
      base_url="https://api.velobase.io/v1",
      default_headers={"X-Velobase-Customer": "user_123"},
  )

  # with_raw_response gives you the billing headers alongside the parsed body
  resp = client.chat.completions.with_raw_response.create(
      model="anthropic/claude-opus-4.8",
      messages=[{"role": "user", "content": "Say hi in three words."}],
      max_tokens=64,
  )
  print(resp.parse().choices[0].message.content)
  print("cost (cents):", resp.headers.get("x-velobase-cost-cents"))
  print("balance (credits):", resp.headers.get("x-velobase-balance-credits"))
  print("txn:", resp.headers.get("x-velobase-transaction-id"))
  ```

  ```typescript Node theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "vb_live_your_project_key",
    baseURL: "https://api.velobase.io/v1",
    defaultHeaders: { "X-Velobase-Customer": "user_123" },
  });

  const { data, response } = await client.chat.completions
    .create({
      model: "anthropic/claude-opus-4.8",
      messages: [{ role: "user", content: "Say hi in three words." }],
      max_tokens: 64,
    })
    .withResponse();

  console.log(data.choices[0].message.content);
  console.log("cost (cents):", response.headers.get("x-velobase-cost-cents"));
  console.log("txn:", response.headers.get("x-velobase-transaction-id"));
  ```

  ```bash curl theme={null}
  curl https://api.velobase.io/v1/chat/completions \
    -H "Authorization: Bearer vb_live_your_project_key" \
    -H "X-Velobase-Customer: user_123" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "anthropic/claude-opus-4.8",
      "messages": [{"role": "user", "content": "Say hi in three words."}],
      "max_tokens": 64
    }'
  ```
</CodeGroup>

## Per-call billing headers

Every non-streaming response carries the billing result on its headers, so you
can show cost and balance without a second request:

| Header                       | Meaning                                                             |
| ---------------------------- | ------------------------------------------------------------------- |
| `x-velobase-cost-cents`      | Cost of this call, in cents                                         |
| `x-velobase-cost-credits`    | Same cost, in credits (1 USD = 100 cents = 1,000,000 credits)       |
| `x-velobase-balance-credits` | The customer wallet's remaining balance after this call, in credits |
| `x-velobase-transaction-id`  | Ties this call to a usage row and ledger entry                      |

These headers are CORS-exposed, so a browser frontend can read them too.

## Streaming

Streaming is supported for OpenAI-protocol models (for example
`deepseek/deepseek-v4-pro`). The billing result arrives as a `velobase` object
on the final stream frame, before `[DONE]`. Request it with
`stream_options: { include_usage: true }`.

<Warning>
  Claude models are routed through Amazon Bedrock, which does not support
  streaming yet. A streaming request for a Claude model returns
  `400 streaming is not yet supported on this model's current route`. Use
  `stream: false` for Claude, or choose a DeepSeek model when you need streaming.
</Warning>

## Fund the customer first

A model call needs a funded customer wallet, otherwise it returns
`402 insufficient_funds`. Top one up before (or right after) you create the user:

<CodeGroup>
  ```python Python theme={null}
  from velobase_billing import Velobase

  vb = Velobase(api_key="vb_live_your_project_key")
  vb.customers.deposit(customer_id="user_123", amount_usd=5)
  ```

  ```typescript Node theme={null}
  import { Velobase } from "@velobaseai/billing";

  const vb = new Velobase({ apiKey: "vb_live_your_project_key" });
  await vb.customers.deposit({ customerId: "user_123", amountUsd: 5 });
  ```

  ```bash curl theme={null}
  curl https://api.velobase.io/v1/customers/user_123/deposit \
    -H "Authorization: Bearer vb_live_your_project_key" \
    -H "Content-Type: application/json" \
    -d '{"amount_usd": 5}'
  ```
</CodeGroup>

See [Depositing Credits](/integration/depositing-credits) for the amount units
and idempotency rules.

## Two wallets

Official (Velobase-routed) models debit two ledgers on each call:

1. The **customer wallet**, your own pricing units, what you charge your end-user.
2. The **project wallet**, real money you prepaid Velobase via Stripe.

A call succeeds only when **both** have funds. If the project wallet runs out,
calls return `402 project_balance_insufficient` regardless of the customer
wallet. Customer deposits are virtual record-keeping and never move real money.

## Reconcile usage

`GET /v1/usage` returns one row per call with `cost_cents`,
`upstream_cost_cents`, token counts, `model`, `customer_id`, and
`transaction_id`. Join it to the `x-velobase-transaction-id` from each response
to reconcile spend per customer.

```bash theme={null}
curl "https://api.velobase.io/v1/usage?limit=20&customer_id=user_123" \
  -H "Authorization: Bearer vb_live_your_project_key"
```

## Next steps

<CardGroup cols={2}>
  <Card title="JavaScript SDK" icon="js" href="/integration/sdk-javascript">
    Deposits, balances and billing primitives from Node/TypeScript.
  </Card>

  <Card title="Python SDK" icon="python" href="/integration/sdk-python">
    The same control-plane operations from Python.
  </Card>
</CardGroup>