Tutorial: Meter Your App

This walks the full loop: get a key, fund an end-customer, make a model call that bills that customer, and reconcile the spend. About 10 minutes.

Get a project key

Sign in to the Velobase Dashboard, open your project, and create an API key under Keys. It looks like vb_live_…. This is your backend key; never ship it to a browser or mobile client.

Fund an end-customer

A model call needs a funded customer wallet. Create/fund one with your app’s own user id:

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}'

amount is integer credits: 1 USD = 1,000,000 credits, so this deposits $5.00. The customer is created on first deposit. In production you call this from your backend after the user pays you, using the payment event id as the idempotency_key.

Make a billed model call

Point the OpenAI SDK at Velobase and tag the call with the customer to bill:

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"},
)
resp = client.chat.completions.with_raw_response.create(
    model="your-model-id",  # one of your project's models, see GET /v1/models
    messages=[{"role": "user", "content": "Write a one-line haiku about billing."}],
    max_tokens=64,
)
print(resp.parse().choices[0].message.content)
print("charged (USD):", resp.headers.get("x-velobase-cost-usd"))
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", // one of your project's models, see GET /v1/models
    messages: [{ role: "user", content: "Write a one-line haiku about billing." }],
    max_tokens: 64,
  })
  .withResponse();
console.log(data.choices[0].message.content);
console.log("charged (USD):", response.headers.get("x-velobase-cost-usd"));

The call debits user_123’s wallet and returns the cost on the response headers. If you see 402 insufficient_balance, the customer wallet is empty; if you see 402 byok_key_required, the model has no upstream provider key attached yet (fix it in the dashboard’s Models section).

Check the balance

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

The available figure dropped by the call’s cost. Or read it through a Python / JavaScript SDK.

Reconcile usage

Every call shows up in usage with its cost, tokens, and transaction id:

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

Match each row’s transaction_id to the x-velobase-transaction-id you got back from the call. That is the full loop: charge per customer, per call, fully reconcilable.

Getting Started

Integration Guides

Dashboard & Management

Advanced Topics

Pricing

Tutorial: Meter Your App

Where to go next

OpenAI-Compatible Gateway

Depositing Credits

​Where to go next

OpenAI-Compatible Gateway

Depositing Credits

Where to go next