OpenAI Compatible API
Relevant source files
The following files were used as context for generating this wiki page:
The freebuff-proxy project provides an OpenAI-compatible API layer that transforms Freebuff free quota into standard API endpoints. This allows downstream agents and tools to interact with Freebuff models using the standard base_url, api_key, and model parameters common to OpenAI integrations. The service manages complex upstream requirements including multi-account pooling, session admission, and request shaping.
Sources: README_EN.md:14-18, CLAUDE.md:31-33
Architecture and Request Flow
The API functions as a reverse proxy. It receives standard OpenAI-formatted requests, performs internal scheduling and translation, and delegates the final upstream communication to a specialized bridge component.
Core Components
- Proxy Entry: Receives downstream requests, parses the requested model, and identifies a valid account from the pool.
- Account Runtimes: Manages the account pool, handling quota monitoring (Freebucks) and cooldown states.
- Signals Translation Layer: Translates tool names and parameter structures between downstream client formats and official upstream requirements.
- CLI Bridge: A specialized component (running on the Bun runtime) that executes the actual upstream calls using official client signatures and device signing.
Sources: src/AGENTS.md:5-15, src/upstream/signals/AGENTS.md:7-14, cli-bridge/AGENTS.md:8-12
Request Data Flow
The following diagram illustrates how a chat/completions request moves through the system:
This diagram shows the path from a downstream OpenAI request to the upstream Freebuff API via the internal proxy components.
Sources: README_EN.md:118-128, src/AGENTS.md:6-14, cli-bridge/AGENTS.md:8-10
Supported Endpoints
The proxy exposes a subset of standard OpenAI endpoints and additional management routes.
| Path | Method | Purpose |
|---|---|---|
/v1/chat/completions | POST | Main chat completion endpoint; handles sessions and passthrough. |
/v1/models | GET | Returns the catalog of available models mapped to internal keys. |
/v1/freebuff/status | GET | Provides a snapshot of current account and session status. |
/v1/freebuff/accounts | GET | Lists account states and cooldown information. |
/healthz | GET | Service liveness probe. |
Sources: README_EN.md:74-81, README.md:79-86
Model Mapping and Translation
The system employs a three-layer mapping for model names. Downstream clients use standard names (e.g., deepseek/deepseek-v4-flash), which the CatalogHolder resolves to the specific keys required by the Freebuff upstream.
Sources: src/AGENTS.md:23-25, README_EN.md:68-70
Tool Name Translation
Downstream clients often provide tool definitions that do not match official Freebuff signatures. The src/upstream/signals/ directory serves as the translation layer:
- Downstream to Official: Maps client-provided tool names to official counterparts (e.g.,
bash). - Parameter Mapping: Translates parameter structures to match the official 37 tools fingerprint.
- Return Path: Translates official tool names back to client-recognized names in the response.
Sources: src/upstream/signals/AGENTS.md:7-17, src/upstream/signals/AGENTS.md:27-31
Quota and Scheduling Logic
The proxy implements specific scheduling rules to protect Freebuff accounts and optimize the "Freebucks" (FB) billing model.
Billing Semantics
- 买断 (Buyout): A session admission buys one full hour of access for a specific model.
- Zero Marginal Cost: Requests made within the purchased hour cost zero additional Freebucks.
- No Refunds: Deleting a session early does not refund the hourly FB cost.
- Persistence: The proxy keeps sessions alive for the duration of the paid hour rather than releasing them when idle.
Sources: README_EN.md:104-108, src/AGENTS.md:52-56
Scheduling Sequence
The scheduling logic prioritizes "sticky" sessions (hot sessions) and drains specific accounts before rotating to new ones to minimize admission costs.
Sources: src/AGENTS.md:60-68, README_EN.md:92-99
Integration Requirements
To connect a downstream agent, you must provide the following configuration:
- Base URL:
http://<host-ip>:8787/v1 - API Key: An internal key generated in the proxy web console (
sk-fb-...). - Model: A model name retrieved from the
/v1/modelsendpoint.
Sources: README_EN.md:62-66, README.md:68-72
# Example curl request
curl http://127.0.0.1:8787/v1/chat/completions \
-H "Authorization: Bearer sk-fb-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek/deepseek-v4-flash","stream":true,
"messages":[{"role":"user","content":"hi"}]}'
Sources: README_EN.md:68-72
Summary
The OpenAI Compatible API in freebuff-proxy acts as a sophisticated translation and scheduling bridge. By handling official device signing, tool fingerprinting, and session-based hourly billing, it allows standard LLM clients to leverage Freebuff's free tier without implementing the complex official protocol themselves. The architecture prioritizes session reuse and account stability through sticky scheduling and centralized signal translation.