01 Quick Start
Your first request
The public API is designed to accept familiar OpenAI-shaped requests while handling provider routing, usage tracking, and prepaid billing behind the scenes.
Create an API key
Sign in to Console, open API Keys, and create a key. Keys use the One Interface prefix and are only shown once.
Choose a priced model
Use the Models page or /v1/models endpoint. Production calls are limited to curated models with configured prices.
Send an OpenAI-compatible request
Point your existing OpenAI SDK at the One Interface base URL and keep the rest of your app mostly unchanged.
from openai import OpenAI
client = OpenAI(
base_url="https://api.oneinterface.ai/v1",
api_key="oi_your_api_key",
)
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Write a one-line haiku about APIs."}],
)
print(response.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.oneinterface.ai/v1",
apiKey: process.env.ONEINTERFACE_API_KEY,
});
const response = await client.chat.completions.create({
model: "claude-sonnet-4-6",
messages: [{ role: "user", content: "Summarize this pull request." }],
});
console.log(response.choices[0].message.content);curl https://api.oneinterface.ai/v1/chat/completions \
-H "Authorization: Bearer oi_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [
{ "role": "user", "content": "Hello from One Interface" }
]
}'02 Authentication
Use a One Interface API key
Every API request must include a bearer token created in Console. The API validates hashed keys server-side and never needs your upstream provider credentials.
Keep keys server-side
Do not expose API keys in browser code. Create requests from your backend, edge function, or another trusted environment.
Authorization: Bearer oi_your_api_key
Content-Type: application/json03 API Reference
Supported endpoints
These routes are implemented by the API service today and proxy to configured upstream providers in priority order.
/v1/chat/completionsChat completions
OpenAI-compatible chat endpoint for conversational and instruction-following models.
modelmessagestemperaturemax_tokensstreamtools/v1/responsesResponses
Forward-compatible endpoint for newer OpenAI-style response payloads.
modelinputinstructionsstreamtoolsmetadata/v1/modelsModels
Returns the curated public model catalog backed by configured model prices.
idobjectcreatedowned_bypricing/v1/embeddingsEmbeddings
OpenAI-compatible embedding endpoint for retrieval, clustering, and search workflows.
modelinputencoding_formatdimensions04 Streaming
Stream chat responses with SSE
Set stream to true on compatible endpoints. One Interface preserves event-stream responses and requests usage data when streaming so billing can be recorded accurately.
await client.chat.completions.create({
model: "gpt-4o",
stream: true,
messages: [{ role: "user", content: "Think step by step." }],
});05 Errors
Stable error shape
Customer-facing errors use a consistent JSON envelope. Raw upstream provider error bodies are not returned to clients.
{
"error": {
"message": "The requested model is not available.",
"type": "oneinterface_error",
"code": "model_not_available"
}
}invalid_api_keyThe bearer token is missing, revoked, or invalid.insufficient_creditThe account balance is too low for a billable request.model_not_availableThe requested model is not in the curated priced catalog.invalid_requestThe body or parameters are malformed.rate_limit_exceededRetry after a short delay.upstream_unavailableAll configured upstream providers are temporarily unavailable.internal_errorUnexpected One Interface service error.06 Console
Keys, usage, and prepaid billing
Console endpoints use Supabase user sessions, while API traffic uses One Interface API keys. Usage events track endpoint, model, token counts, status, billing status, and cost.
Prepaid balance
Billable requests require a positive account balance. Stripe Checkout top-ups are supported.
Provider routing
The API tries configured upstreams in priority order and records the selected provider internally.
Curated pricing
Models must exist in the model price table unless unpriced models are explicitly allowed.
07 Integrations
Use One Interface inside Cursor, Claude Code, and Codex
One Interface works as a drop-in OpenAI-compatible provider in any AI coding tool. For Claude Code, a native MCP server is also available — giving Claude direct access to 200+ models plus full account management.
Cursor
Add One Interface as a custom OpenAI-compatible provider, then paste the base URL, API key, and model ID.
Claude Code
Three integration modes: OpenAI-compatible provider, native Anthropic API proxy via ANTHROPIC_BASE_URL (routes Claude Code's own model calls through One Interface), or native MCP server for direct access to 200+ models and full account management.
Codex
Point your Codex provider configuration at One Interface and select the model you want to use for coding sessions.
Option A — OpenAI-compatible provider (Cursor, Codex, all tools)
- Create a One Interface API key from Console.
- Open your coding tool's model, provider, or extension settings.
- Add a custom OpenAI-compatible provider.
- Set the base URL to
https://api.oneinterface.ai/v1. - Paste your
oi_...API key and choose a model ID from/v1/models. - Save the provider, then select it for chat, agent, or code-generation workflows.
Provider type: OpenAI-compatible
Base URL: https://api.oneinterface.ai/v1
API key: oi_your_api_key
Model: gpt-4o, claude-sonnet-4-6, or any model ID from /v1/models# Example custom provider shape for tools that support provider config
provider = "oneinterface"
base_url = "https://api.oneinterface.ai/v1"
api_key_env = "ONEINTERFACE_API_KEY"
model = "claude-sonnet-4-6"Option B — Anthropic API proxy (Claude Code only)
One Interface exposes a /v1/messages endpoint that accepts the native Anthropic Messages API format and translates it to your configured upstream providers. Setting ANTHROPIC_BASE_URL routes Claude Code's own model calls — including tool use and streaming — through One Interface, billed to your account.
- Create a One Interface API key from Console.
- Set
ANTHROPIC_API_KEYto youroi_...key andANTHROPIC_BASE_URLtohttps://api.oneinterface.ai. - Launch Claude Code with
--bare --model <model-id>. The--bareflag forces Claude Code to use your API key instead of its OAuth session — without it requests will fail with 401. Choose any model ID from/v1/models(e.g.gpt-4o-mini).
# --bare forces Claude Code to use ANTHROPIC_API_KEY instead of its OAuth session.
# Without --bare the OAuth token is sent to One Interface and rejected (401).
ANTHROPIC_API_KEY=oi_your_api_key \
ANTHROPIC_BASE_URL=https://api.oneinterface.ai \
claude --bare --model gpt-4o-mini
# Recommended: add an alias to ~/.zshrc so you just type "claude-oi"
alias claude-oi='ANTHROPIC_API_KEY=oi_your_api_key ANTHROPIC_BASE_URL=https://api.oneinterface.ai claude --bare --model gpt-4o-mini'Option C — Native MCP remote server (Claude Code only)
The MCP server runs at https://api.oneinterface.ai/mcp and exposes seven tools Claude can call directly: chat_completion, get_balance, list_models, list_api_keys, create_api_key, revoke_api_key, and get_usage.
- Create a One Interface API key from Console (or copy your session token from Console → Settings → Claude Code MCP).
- Run the command below in your terminal, replacing the placeholder key. This registers the server globally across all your projects.
- Verify with
claude mcp list— oneinterface should show ✓ Connected. - Ask Claude anything: “What models does OneInterface have?” or “Use gpt-4o-mini to summarise this file.”
# Run once in your terminal — registers the server for all your projects
claude mcp add --transport http -s user oneinterface https://api.oneinterface.ai/mcp \
-H "Authorization: Bearer oi_your_api_key"
# Verify the connection
claude mcp list08 Deployment
Operational references
The repository also includes deeper setup documents for local development, backend deployment, environment variables, and product gaps.
Need a model catalog?
Browse public model availability and pricing, then call the selected model ID from any OpenAI-compatible SDK.