Docs — CoffeeVibeAI

Introduction

CoffeeVibeAI is a unified AI gateway. Instead of managing separate subscriptions and keys for Anthropic, OpenAI, and Google, you sign up once and get a single CoffeeVibeAI API key (prefixed sk-) that routes to whichever model you request — Claude, GPT, or Gemini — over the same endpoint.

Usage is metered in USD against the balance on your key, with per-key quota windows and rate limits you can inspect at any time. There's no separate provider account to connect — your CoffeeVibeAI key is what you authenticate with, and your CoffeeVibeAI dashboard is where you top up and track spend.

Quick Start

Get your first response back in under a minute.

1. Create an account

Sign up on the dashboard, then open the API Keys page and generate a key. Every key starts with sk- and is shown once at creation.

2. Point your client at the gateway

Using Claude Code CLI? Run the one-command installer instead and skip straight to step 4 — see Claude Code one-command setup below. Otherwise, set the standard Anthropic SDK env vars by hand:

# works with the standard Anthropic SDK env var
export ANTHROPIC_BASE_URL="https://api.coffeevibeai.com"
export ANTHROPIC_API_KEY="sk-your-coffeevibeai-key"

3. Make a request

curl https://api.coffeevibeai.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1024,"messages":[{"role":"user","content":"hello"}]}'

→

The request is metered against your key's balance and shows up immediately in your dashboard — model, tokens, cost, and latency.

Account & API Keys

Every account can hold multiple sk- keys, each with its own optional quota, rate limit, and expiry date — useful for separating projects or issuing scoped keys to teammates.

Keys are shown once at creation and stored hashed — if you lose one, revoke it and create a new one.
Revoking a key from the dashboard takes effect immediately; there's no grace period.
A key with no quota configured is unrestricted and draws directly against your account balance. A key with a quota or rate-limit window set reports quota_limited status via the usage endpoint below.

API Reference

Authenticate with your key via the Authorization: Bearer sk-... header (also accepted as x-api-key or x-goog-api-key for clients that expect those). Endpoints mirror the upstream provider's own request and response shape — no altered fields.

Method	Endpoint	Description
POST	/v1/messages	Anthropic Messages API. Streaming supported.
POST	/v1/chat/completions	OpenAI Chat Completions–compatible endpoint. Streaming supported.
POST	/v1/responses	OpenAI Responses API–compatible endpoint, including Codex-style tool use.
POST	/v1/embeddings	Text embeddings, OpenAI-compatible request/response shape.
POST	/v1/images/generations	Image generation. `/v1/images/edits` and async `/async` variants also available.
POST	/v1/videos/generations	Video generation. `/v1/videos/edits` and `/extensions` also available.
POST	/v1/tts	Text to speech.
POST	/v1/stt	Speech to text.
GET	/v1/models	Lists models available to your key.
GET	/v1/usage	Returns quota, balance, rate-limit windows, and usage stats for the calling key.

Supported models

The Claude lineup is routed 1:1 by model ID — including claude-fable-5, claude-opus-5, claude-sonnet-5, and the 4.x series. OpenAI-compatible and Gemini models are available through their respective endpoints; call GET /v1/models for the exact list enabled on your key.

Checking usage

curl -s "https://api.coffeevibeai.com/v1/usage" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY"

Returns your key's quota (limit/used/remaining in USD), any configured rate_limits windows (5h / 1d / 7d), and a breakdown of usage by day and by model.

Editor & CLI Integrations

Anything that reads a base URL environment variable works without a plugin.

Claude Code

One-command installer configures env vars and settings.json — see setup guide.

Cursor

Set the base URL in .cursorrules or model settings.

Windsurf

Same environment variable convention as Cursor.

Aider

Pass --openai-api-base or use the env var directly.

LangChain

Set base_url on your ChatAnthropic or ChatOpenAI client.

OpenWebUI

Add as a custom OpenAI-compatible connection.

Claude Code One-Command Setup

Skip the manual env vars. Grab the install command from the Use API Key modal next to any key in your dashboard (it comes pre-filled with that key), or copy it here and swap in your own key:

curl -fsSL "https://api.coffeevibeai.com/install.sh?key=YOUR_KEY" | bash

This runs an interactive installer (macOS & Linux) that:

Detects every shell rc file you have (.zshrc, .bashrc, .bash_profile), backs each one up, and appends the gateway's env vars.
Writes the same values into ~/.claude/settings.json, merging with whatever is already there — it never overwrites unrelated settings.
Prompts you to pick which Opus and Sonnet model version to pin (Haiku has one current version, so it's set automatically). Pass --opus= / --sonnet= to skip the prompts in a non-interactive shell.
On macOS, also applies the vars via launchctl setenv so GUI apps (not just terminal shells) pick them up immediately, no reboot needed.
Removes any existing ANTHROPIC_API_KEY it finds — Claude Code warns and behaves nondeterministically if both that and ANTHROPIC_AUTH_TOKEN are set, and the gateway needs the token form.

What lands in settings.json

The installer merges these keys under env in ~/.claude/settings.json (or your project-level .claude/settings.json if you point it there):

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.coffeevibeai.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-coffeevibeai-key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

Note the auth field is ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY — Claude Code uses the token form for gateway-style auth. If you're editing settings.json by hand instead of running the installer, use the same field name.

Removing it

curl -fsSL "https://api.coffeevibeai.com/install.sh" | bash -s -- --uninstall

Reverts every shell config and settings.json change the installer made, and clears the macOS launchctl vars. Backups of every file it touched are left alongside the original with a .backup.<timestamp> suffix.

Reliability & Failover

Behind your single API key, CoffeeVibeAI pools capacity across multiple upstream accounts per provider. If one upstream account is rate-limited or returns an error, the gateway retries on another account in the same pool automatically — you don't manage or see individual upstream credentials.

Retries happen transparently within a request; there's no fallback config for you to write.
Per-provider capacity is monitored continuously, and degraded upstreams are routed around.
If a whole provider is down, requests to that provider's models will fail with the same error type it returns upstream (e.g. overloaded_error) — switching to a different model is on you.

Usage & Billing

CoffeeVibeAI meters usage in USD against the balance on your key. Top up from the dashboard (card, Alipay, or WeChat Pay depending on region), then spend it down across any supported model.

Every key can have its own total quota and 5h / 1d / 7d rate-limit windows, or be left unrestricted to draw directly against your account balance.
GET /v1/usage returns live quota, remaining balance, current rate-limit windows, and a per-model, per-day breakdown — the same numbers shown in the dashboard.
A request against a key with insufficient balance is rejected before it reaches the upstream provider, returned as an insufficient_quota error.

Everything you need to get an API key.