Copy for AI - Velobase

Paste the block below into your AI coding assistant (Cursor, Claude Code, etc.), then tell it what to build. It covers the full surface: the model gateway, the customer wallets, and the billing primitives, with every endpoint, its purpose, and the units, so the assistant can write a correct integration in one shot.

Replace vb_live_... with a real project key from Dashboard → Keys, and use your own stable user id wherever you see user_123.

You are integrating Velobase into my app. Velobase is an OpenAI/Anthropic-compatible
AI gateway that bills every model call to one of MY end-customers' wallets, plus a
billing ledger for work I price myself. Use the reference below; wire up the parts I ask for.

# Setup
- Base URL: https://api.velobase.io/v1   (the OpenAI SDK base_url needs the /v1 suffix)
- Auth header: Authorization: Bearer <key>
  - vb_live_...      project key (server-side). Pick who to bill with header X-Velobase-Customer: <your-user-id>.
  - vb_customer_...  customer-scoped key (carries its own customer; no header needed).
- Amount units: amount_usd / amount_cents / amount_credits. 1 USD = 100 cents = 1,000,000 credits.
- Idempotency: pass idempotency_key (or the Idempotency-Key header) on writes; safe to retry, never double-applies.
- Errors are JSON: { "error": { "type", "message", "request_id" } }.

# Gateway: model calls, billed to the customer's wallet
- POST /v1/chat/completions   OpenAI-compatible chat completions. Send X-Velobase-Customer.
- POST /v1/messages           Anthropic-style endpoint (today returns OpenAI-shaped bodies for OpenAI-route models).
- GET  /v1/models             List the models your project can route.
- GET  /v1/usage              Per-call usage rows: cost_cents, upstream_cost_cents, tokens, model, customer_id, transaction_id, status. Supports ?customer_id= and ?limit=.
- Per-call billing comes back on response headers:
    x-velobase-cost-cents, x-velobase-cost-credits, x-velobase-balance-credits, x-velobase-transaction-id
- Streaming: OpenAI-route models (e.g. deepseek/deepseek-v4-pro) support it. Claude models route via Bedrock and do NOT support streaming yet (use stream:false for Claude).
- Available models: deepseek/deepseek-v4-pro (streaming);
    anthropic/claude-opus-4.5, claude-opus-4.6, claude-opus-4.7, claude-opus-4.8,
    claude-sonnet-4.6, claude-haiku-4.5 (non-streaming).
- Example (Python, official OpenAI SDK):
    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="deepseek/deepseek-v4-pro",
        messages=[{"role":"user","content":"Hello"}], max_tokens=256)
    print(r.parse().choices[0].message.content, r.headers.get("x-velobase-cost-cents"))

# Customers and wallets (control-plane)
- POST /v1/customers/deposit              body { customer_id, amount_usd }  fund a customer wallet (created on first deposit).
    also accepts POST /v1/customers/{id}/deposit
- GET  /v1/customers/{id}                 -> { id, name, email, metadata,
    wallets: { "<wallet>": { total, used, frozen, available,
      sources: [ { source, total, used, frozen, available, starts_at, expires_at } ] } },
    created_at }
- GET  /v1/customers/{id}/balance         -> { object:"customer.balance", balance: { totalSummary:{total,used,frozen,available}, accounts:[...] } }
- GET  /v1/customers/{id}/ledger          -> { items:[ { id, operation_type, amount, wallet, source, transaction_id, business_type, status, created_at } ], has_more, next_cursor }

# Billing primitives: for work YOU price (model calls bill automatically, you do NOT call these for them)
- POST /v1/billing/deduct     body { customer_id, transaction_id, amount }   charge a known cost now.
- POST /v1/billing/freeze     body { customer_id, transaction_id, amount }   reserve a budget before a task.
- POST /v1/billing/consume    body { transaction_id, actual_amount }         settle the actual cost; the remainder is released.
- POST /v1/billing/unfreeze   body { transaction_id }                        cancel a freeze; release everything.

# SDKs (control-plane only: deposits, balances, freeze/consume). Model calls go through the OpenAI/Anthropic SDK above.
- Python: pip install "velobase-billing>=0.2.1"
    from velobase_billing import Velobase
    vb = Velobase(api_key="vb_live_...")
    vb.customers.deposit(customer_id="user_123", amount_usd=5)
    vb.customers.get("user_123").wallets["default"].available
    vb.customers.ledger("user_123")
    vb.billing.freeze(customer_id="user_123", transaction_id="job_1", amount=50)
    vb.billing.consume(transaction_id="job_1", actual_amount=32)
- JavaScript: npm i @velobaseai/billing@^1.1.1
    import { Velobase } from "@velobaseai/billing";
    const vb = new Velobase({ apiKey: "vb_live_..." });
    await vb.customers.deposit({ customerId: "user_123", amountUsd: 5 });

# Two wallets (how the money works)
- Customer wallet: your own pricing units, what you charge your end-user. Funded by deposit.
- Project wallet: real money you prepaid Velobase via Stripe. Official models debit it for platform cost.
- A model call needs BOTH funded: 402 insufficient_funds = customer wallet empty; 402 project_balance_insufficient = top up the project wallet.

Now build what I ask for next. Default to the OpenAI SDK + X-Velobase-Customer for model calls,
and the velobase-billing SDK (or POST /v1/customers/deposit) for funding customers.

What to do with it

Tell the assistant the specific task, for example:

“Route my existing OpenAI calls through Velobase and bill each one to the signed-in user.”
“In my Stripe webhook, top up the paying customer’s Velobase wallet with the amount they paid.”
“Show each user their remaining balance and a usage history in my dashboard.”

For deeper reference see the OpenAI-compatible gateway, the Python and JavaScript SDKs, and depositing credits.

​What to do with it

What to do with it