Documentation

Build on every model through one OpenAI-compatible API.

Start with the SDKs you already use, route requests through One Interface, and manage keys, balances, usage, and model pricing from one Console.

Base URLhttps://api.oneinterface.ai/v1
AuthAuthorization: Bearer oi_...
CompatibilityOpenAI SDKs, cURL, server clients

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.

Python
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)
Node.js
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
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.

Header
Authorization: Bearer oi_your_api_key
Content-Type: application/json

03 API Reference

Supported endpoints

These routes are implemented by the API service today and proxy to configured upstream providers in priority order.

POST/v1/chat/completions

Chat completions

OpenAI-compatible chat endpoint for conversational and instruction-following models.

modelmessagestemperaturemax_tokensstreamtools
POST/v1/responses

Responses

Forward-compatible endpoint for newer OpenAI-style response payloads.

modelinputinstructionsstreamtoolsmetadata
GET/v1/models

Models

Returns the curated public model catalog backed by configured model prices.

idobjectcreatedowned_bypricing
POST/v1/embeddings

Embeddings

OpenAI-compatible embedding endpoint for retrieval, clustering, and search workflows.

modelinputencoding_formatdimensions

04 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.

Streaming request
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 response
{
  "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)

  1. Create a One Interface API key from Console.
  2. Open your coding tool's model, provider, or extension settings.
  3. Add a custom OpenAI-compatible provider.
  4. Set the base URL to https://api.oneinterface.ai/v1.
  5. Paste your oi_... API key and choose a model ID from /v1/models.
  6. Save the provider, then select it for chat, agent, or code-generation workflows.
Provider settings
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
Codex-style provider config
# 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.

  1. Create a One Interface API key from Console.
  2. Set ANTHROPIC_API_KEY to your oi_... key and ANTHROPIC_BASE_URL to https://api.oneinterface.ai.
  3. Launch Claude Code with --bare --model <model-id>. The --bare flag 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).
Terminal — route Claude Code through One Interface
# --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.

  1. Create a One Interface API key from Console (or copy your session token from Console → Settings → Claude Code MCP).
  2. Run the command below in your terminal, replacing the placeholder key. This registers the server globally across all your projects.
  3. Verify with claude mcp listoneinterface should show ✓ Connected.
  4. Ask Claude anything: “What models does OneInterface have?” or “Use gpt-4o-mini to summarise this file.”
Terminal — register MCP server
# 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 list

08 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.

View models