OpenAI-Compatible Gateway

Velobase is a model-agnostic, OpenAI-compatible AI gateway. Point your OpenAI SDK at it and call any model your project has configured, 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.

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.

Your models

Models are defined per project, and you bring your own upstream key (BYOK). In the dashboard’s Models section you add a model with three things:

a public model id (what your app passes as model),
the price your customers pay, per million tokens,
the upstream provider key it routes to.

GET /v1/models returns exactly the models your project has configured, with per-model pricing in both credits and USD (input_price_per_million_credits, input_price_per_million_usd, output_price_per_million_credits, output_price_per_million_usd, plus cache_read_... and cache_write_... variants), along with context_window, max_output_tokens, display_name, description, and active. There is no platform-wide model list. A model that exists but has no upstream provider key attached returns 402 byok_key_required (an operator configuration issue, distinct from customer balance).

Copy for AI

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

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>
- Models are whatever my project configured in the dashboard; list them with GET /v1/models.

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="<a model id from GET /v1/models>",
    messages=[{"role": "user", "content": "Hello"}], max_tokens=256)
# billing on headers: X-Velobase-Cost-Credits / -Cost-Usd /
#                     -Balance-Credits / -Balance-Usd / -Transaction-Id / -Trace-Id
print(r.parse().choices[0].message.content)

Fund a customer first (else 402 insufficient_balance):
POST /v1/customers/deposit {"customer_id": "user_123", "amount": 5000000}
(amount is integer credits; 1 USD = 1,000,000 credits, so 5000000 = $5.00)
Reconcile: GET /v1/usage (filter by customer_id / model / transaction_id / trace_id)
Streaming: supported on /v1/chat/completions and /v1/messages; cost/usage arrives
in the final standard frame (OpenAI: last usage chunk; Anthropic: message_delta).
402 byok_key_required means the model has no upstream provider key attached in
the dashboard. Control-plane SDK: npm i @velobaseai/billing@^1.2.0.

Make a call

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="your-model-id",
    messages=[{"role": "user", "content": "Say hi in three words."}],
    max_tokens=64,
)
print(resp.parse().choices[0].message.content)
print("cost (USD):", resp.headers.get("x-velobase-cost-usd"))
print("balance (credits):", resp.headers.get("x-velobase-balance-credits"))
print("txn:", resp.headers.get("x-velobase-transaction-id"))

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: "your-model-id",
    messages: [{ role: "user", content: "Say hi in three words." }],
    max_tokens: 64,
  })
  .withResponse();

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

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": "your-model-id",
    "messages": [{"role": "user", "content": "Say hi in three words."}],
    "max_tokens": 64
  }'

Images and PDFs

Chat requests can carry images and PDF documents inline, on both protocols, for any model whose upstream supports them:

Images: OpenAI-style image_url parts (a data: URL with base64 bytes, or a plain https: URL), and Anthropic-style image blocks (base64 or url source). The detail field is passed through.
PDFs: OpenAI-style file parts (file.file_data as a base64 data URL), and Anthropic-style document blocks (base64 source). Documents referenced only by URL are rejected with unsupported_content; send the bytes.
Images inside tool results (Anthropic protocol): when a tool returns an image, the gateway re-emits it to the model right after the tool message, so it is never silently dropped.

Audio and video input, file upload endpoints (/v1/files), and image generation are out of scope; the gateway covers chat with inline vision and documents. Billing needs no extra setup: the upstream’s own token accounting already prices media, and the gateway settles from it. For the pre-call hold, the gateway estimates images from their pixel dimensions and PDFs from their page count (read from the file header, never decoded), so required_credits on a 402 stays close to what the call will really cost.

How the hold is sized

Before forwarding, the gateway places a temporary hold on the customer’s wallet: an input part estimated from the request (text length, image dimensions, PDF pages) plus an output part sized from max_tokens. When the call finishes, the real cost is settled and the rest of the hold is released. Set max_tokens on every request you can. Without it the output part is reserved at 8,000 tokens, which raises the balance a customer needs to clear the 402 check far above the call’s typical cost.

Request headers

Header	Meaning
`X-Velobase-Customer`	The end-customer to bill (required with a `vb_live_` project key; not needed with a `vb_customer_` key)
`X-Velobase-Wallet`	Bill a specific wallet instead of the default `credits` wallet
`X-Velobase-Trace-Id`	Your correlation id; echoed on the response, queryable via `GET /v1/usage?trace_id=`
`Idempotency-Key`	Unique key per logical request. Replaying the same key returns `409` instead of double-charging; use a fresh key per new request and reuse it only for retries of the same request

Per-call billing headers

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

Header	Meaning
`X-Velobase-Cost-Credits`	Cost of this call, in credits (1 USD = 1,000,000 credits)
`X-Velobase-Cost-Usd`	The same cost, in USD
`X-Velobase-Balance-Credits`	The customer wallet’s remaining balance after this call, in credits
`X-Velobase-Balance-Usd`	The same balance, in USD
`X-Velobase-Transaction-Id`	Ties this call to a usage row and ledger entry
`X-Velobase-Trace-Id`	Your correlation id, echoed back

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

Streaming

Streaming is supported on both POST /v1/chat/completions and POST /v1/messages. The billing result arrives in the final standard frame of the stream: for OpenAI-protocol streams it rides the last usage chunk (before [DONE]), and for Anthropic-protocol streams it rides the message_delta event. Usage accounting works the same for streaming and non-streaming calls.

Fund the customer first

A model call needs a funded customer wallet, otherwise it returns 402 insufficient_balance (the body includes the required and available credit amounts, so you can drive a paywall from it). Top one up before (or right after) you create the user. amount is integer credits: 1 USD = 1,000,000 credits.

import { Velobase } from "@velobaseai/billing";

const vb = new Velobase({ apiKey: "vb_live_your_project_key" });
await vb.customers.deposit({ customerId: "user_123", amount: 5_000_000 }); // $5.00

curl -X POST https://api.velobase.io/v1/customers/deposit \
  -H "Authorization: Bearer vb_live_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "user_123", "amount": 5000000}'

See Depositing Credits for wallets, validity windows, and idempotency rules.

Where the money comes from

Each model call settles against exactly one ledger: the end-customer’s wallet, in your pricing units. The upstream provider bills you directly on the API key you attached to the model (BYOK); Velobase does not resell tokens. Two 402s to tell apart:

402 insufficient_balance: the customer’s wallet cannot cover the call. Fix by depositing.
402 byok_key_required: the model has no upstream provider key attached. Fix in the dashboard’s Models section.

Reconcile usage

GET /v1/usage returns one row per call. Filter with customer_id, model, transaction_id, trace_id, and paginate with cursor and limit. Join rows to the X-Velobase-Transaction-Id from each response to reconcile spend per customer. Each billed call also has a receipt at GET /v1/billing/receipts/:transaction_id.

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

Getting Started

Integration Guides

Dashboard & Management

Advanced Topics

Pricing

OpenAI-Compatible Gateway

Your models

Copy for AI

Make a call

Images and PDFs

How the hold is sized

Request headers

Per-call billing headers

Streaming

Fund the customer first

Where the money comes from

Reconcile usage

Next steps

JavaScript SDK

Python SDK

​Your models

​Copy for AI

​Make a call

​Images and PDFs

​How the hold is sized

​Request headers

​Per-call billing headers

​Streaming

​Fund the customer first

​Where the money comes from

​Reconcile usage

​Next steps

JavaScript SDK

Python SDK

Your models

Copy for AI

Make a call

Images and PDFs

How the hold is sized

Request headers

Per-call billing headers

Streaming

Fund the customer first

Where the money comes from

Reconcile usage

Next steps