Quickstart

Velobase is an AI gateway first: point your existing OpenAI or Anthropic SDK at it, and every model call is billed to one of your end-customers’ wallets. It is also a billing ledger (freeze, consume, deduct) for work you price yourself. This quickstart covers the gateway path first, then the billing ledger primitives.

Get your API key

Sign in to the Velobase Dashboard.
Create a project if you haven’t already.
Go to Keys and generate a new key.

You can create two kinds of keys:

vb_live_ is a project key. Use it server-side and tell Velobase who to bill with the X-Velobase-Customer: <user-id> header.
vb_customer_ is a customer-scoped key. It carries its own customer binding, so no header is needed.

Fund a customer wallet

Add funds to a customer’s wallet. If the customer does not exist yet, Velobase creates them automatically.amount is a positive integer number of credits: 1 credit = 1 micro-USD, so 1 USD = 1,000,000 credits.

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

This deposits 1,000,000 credits, which is $1.00.

Make a model call

Point your OpenAI or Anthropic SDK at https://api.velobase.io/v1 and pass X-Velobase-Customer to say which wallet to bill. Models are defined per project: in the dashboard, add a model with a public id, your price, and your own upstream provider key, then call it by that id. GET /v1/models lists your project’s models.

curl -X POST https://api.velobase.io/v1/chat/completions \
  -H "Authorization: Bearer your_api_key_here" \
  -H "X-Velobase-Customer: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{ "role": "user", "content": "Hello!" }],
    "max_tokens": 256
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.velobase.io/v1",
    api_key="your_api_key_here",
)

resp = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=256,
    extra_headers={"X-Velobase-Customer": "user_123"},
)
print(resp.choices[0].message.content)

Always set max_tokens. Before each call the gateway places a temporary hold on the customer’s wallet (released or settled when the call finishes), and the output part of that hold is sized from max_tokens. Without it the gateway reserves for a large 8,000-token output, so customers need a much bigger balance to pass the 402 check than the call will actually cost.

Velobase forwards the request upstream, settles the real token cost against the customer’s wallet, and returns per-call billing details in the response headers:

X-Velobase-Cost-Credits and X-Velobase-Cost-Usd: what this call cost.
X-Velobase-Balance-Credits and X-Velobase-Balance-Usd: the wallet balance after the call.
X-Velobase-Transaction-Id: the ledger transaction for this call.
X-Velobase-Trace-Id: your correlation id, echoed back if you sent one.

Streaming is supported on both endpoints; the cost and usage arrive in the final standard frame of the stream (OpenAI: the last usage chunk; Anthropic: message_delta).

You can list your project’s models with GET /v1/models and review per-call spend with GET /v1/usage. A model whose upstream provider key has not been attached yet returns 402 byok_key_required.

Bill work you price yourself (optional)

For work that is not a model call (for example image generation or a fixed-price feature), use the billing ledger primitives directly. Charge a customer in two ways:

Use direct deduction when the cost is known upfront.
Use staged deduction when the final cost is only known after execution.

Amounts are positive integer credits (1 USD = 1,000,000 credits).

Option A: Direct deduction
Option B: Staged deduction

Use this for fixed-price operations such as image generation or a known API call cost.

curl -X POST https://api.velobase.io/v1/billing/deduct \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "transaction_id": "img_gen_001",
    "amount": 200000
  }'

This deducts 200,000 credits ($0.20) immediately.

Use this when you only know the maximum budget before the task starts.Freeze first

curl -X POST https://api.velobase.io/v1/billing/freeze \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "transaction_id": "llm_task_001",
    "amount": 200000
  }'

This reserves 200,000 credits ($0.20) before the task starts.Consume the actual cost

curl -X POST https://api.velobase.io/v1/billing/consume \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "llm_task_001",
    "actual_amount": 120000
  }'

Velobase consumes 120,000 credits (

0.12) and automatically returns the remaining 80,000 credits (

0.08).If the task is cancelled, call unfreeze instead of consume.

Check the wallet

curl https://api.velobase.io/v1/customers/user_123 \
  -H "Authorization: Bearer your_api_key_here"

Response:

{
  "id": "user_123",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "metadata": {},
  "wallets": {
    "credits": {
      "total": 1000000,
      "used": 120000,
      "frozen": 0,
      "available": 880000,
      "sources": [
        {
          "source": "deposit",
          "total": 1000000,
          "used": 120000,
          "frozen": 0,
          "available": 880000,
          "starts_at": null,
          "expires_at": null
        }
      ]
    }
  },
  "created_at": "2026-06-17T00:00:00Z"
}

Wallet amounts are reported in credits (1,000,000 credits = 1 USD).

SDKs

Prefer a typed client? Install the Velobase JavaScript SDK and pin the version:

npm i @velobaseai/billing@^1.2.0

From Python, call the REST endpoints directly (as in the cURL examples above) and use the OpenAI SDK for gateway calls.

Next steps

Funding wallets

Wallet categories, validity periods, and balance breakdown.

Direct deduction

Charge immediately when cost is known.

Staged deduction

Freeze first, then settle the actual cost.

API reference

Complete endpoint reference.

Getting Started

Integration Guides

Dashboard & Management

Advanced Topics

Pricing

SDKs

Next steps

Funding wallets

Direct deduction

Staged deduction

API reference

​SDKs

​Next steps

Funding wallets

Direct deduction

Staged deduction

API reference

SDKs

Next steps