Quickstart

BVE Gateway is a drop-in replacement for the OpenAI API. Point your SDK’s base URL at https://api.bve.me/v1 and use your sk-bve- key.

1. Install the SDK

   TypeScript

   bun add openai
   # or: npm install openai

   Python

   pip install openai

   cURL

   No installation needed — curl ships with macOS and most Linux distributions.

2. Make your first request

   TypeScript

   import OpenAI from 'openai';
   
   const client = new OpenAI({
     apiKey: 'sk-bve-YOUR_KEY',
     baseURL: 'https://api.bve.me/v1',
   });
   
   const response = await client.chat.completions.create({
     model: 'gpt-4o',
     messages: [{ role: 'user', content: 'Hello!' }],
   });
   
   console.log(response.choices[0].message.content);

   Python

   from openai import OpenAI
   
   client = OpenAI(
       api_key="sk-bve-YOUR_KEY",
       base_url="https://api.bve.me/v1",
   )
   
   response = client.chat.completions.create(
       model="gpt-4o",
       messages=[{"role": "user", "content": "Hello!"}],
   )
   
   print(response.choices[0].message.content)

   cURL

   curl https://api.bve.me/v1/chat/completions \
     -H "Authorization: Bearer sk-bve-YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "gpt-4o",
       "messages": [{ "role": "user", "content": "Hello!" }]
     }'

3. Verify the gateway is reachable

   No auth required — call /health to confirm the gateway is up:

   curl https://api.bve.me/health

   {
     "status": "ok",
     "service": "bve-gateway",
     "timestamp": "2026-05-21T12:00:00.000Z",
     "request_id": "550e8400-e29b-41d4-a716-446655440000"
   }

4. Discover available models

   List all models your key can access, optionally filtered by capability type:

   TypeScript

   // All models
   const models = await client.models.list();
   for (const model of models.data) {
     console.log(model.id, (model as Record<string, unknown>).bve_category);
   }
   
   // Only chat models
   const chatModels = await fetch(
     'https://api.bve.me/v1/models?category=chat',
     { headers: { Authorization: 'Bearer sk-bve-YOUR_KEY' } }
   );

   Python

   import httpx
   
   # All models
   models = client.models.list()
   for model in models.data:
       print(model.id)
   
   # Only embedding models
   r = httpx.get(
       "https://api.bve.me/v1/models",
       params={"category": "embedding"},
       headers={"Authorization": "Bearer sk-bve-YOUR_KEY"},
   )
   print(r.json()["data"])

   cURL

   # All models
   curl https://api.bve.me/v1/models \
     -H "Authorization: Bearer sk-bve-YOUR_KEY"
   
   # Only chat models
   curl "https://api.bve.me/v1/models?category=chat" \
     -H "Authorization: Bearer sk-bve-YOUR_KEY"

   Each model entry includes bve_category (chat, embedding, image, tts, transcription, ocr) and bve_endpoints (the gateway paths that accept the model). Use ?category= or ?endpoint=/v1/chat/completions to narrow the list.

5. Check your quota

   After your first request, verify how much of your rate-limit window is consumed:

   TypeScript

   const res = await fetch('https://api.bve.me/v1/usage', {
     headers: { Authorization: 'Bearer sk-bve-YOUR_KEY' },
   });
   const usage = await res.json() as {
     object: string;
     key_id: string;
     this_minute: { used: number; limit: number | null; remaining: number | null };
     today: { used: number; limit: number | null; remaining: number | null };
     this_month: {
       requests: { used: number; limit: number | null };
       tokens: { used: number; limit: number | null };
     };
   };
   console.log('Requests this minute:', usage.this_minute.used);
   console.log('Requests today:', usage.today.used);

   Python

   import httpx
   
   r = httpx.get(
       "https://api.bve.me/v1/usage",
       headers={"Authorization": "Bearer sk-bve-YOUR_KEY"},
   )
   usage = r.json()
   print("Requests this minute:", usage["this_minute"]["used"])
   print("Requests today:", usage["today"]["used"])

   cURL

   curl https://api.bve.me/v1/usage \
     -H "Authorization: Bearer sk-bve-YOUR_KEY"

   The response uses live counters from the quota Durable Object. null limits mean no cap is set for that window. See the Usage Snapshot reference for the full field list.

Next steps

Authentication Key format, CORS headers, and all auth error codes — plus the admin key scheme.

Chat Completions Full request/response reference for /v1/chat/completions with streaming.

Models Filter available models by category, provider, endpoint, or search term.

Usage Snapshot Check real-time quota consumption — does not consume a request.

SDK Usage TypeScript and Python examples for every endpoint using the OpenAI, Anthropic, and Groq SDKs.

Rate Limits & Quotas Per-key RPM/RPD limits, monthly caps, and Retry-After handling.