Connection basics
Use this base URL
https://api.cheaperinference.com/v1
Before you start
Create an API key, then copy an exact model ID from the live model catalog. Store keys in an environment variable when the app supports it.
SDKs and application frameworks
Use the official OpenAI clients or an OpenAI-compatible framework. Keep the library's normal request shape; change only its API key and base URL.
OpenAI Node SDK
import OpenAI from "openai";const client = new OpenAI({ apiKey: process.env.CHEAPER_INFERENCE_API_KEY, baseURL: "https://api.cheaperinference.com/v1",});const response = await client.chat.completions.create({ model: "gpt-5.4", messages: [{ role: "user", content: "Hello" }],});OpenAI Python SDK
import osfrom openai import OpenAIclient = OpenAI( api_key=os.environ["CHEAPER_INFERENCE_API_KEY"], base_url="https://api.cheaperinference.com/v1",)response = client.chat.completions.create( model="gpt-5.4", messages=[{"role": "user", "content": "Hello"}],)Vercel AI SDK
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";import { generateText } from "ai";const cheaperInference = createOpenAICompatible({ name: "cheaper-inference", apiKey: process.env.CHEAPER_INFERENCE_API_KEY, baseURL: "https://api.cheaperinference.com/v1",});const { text } = await generateText({ model: cheaperInference("gpt-5.4"), prompt: "Hello",});LangChain
import osfrom langchain_openai import ChatOpenAImodel = ChatOpenAI( model="gpt-5.4", api_key=os.environ["CHEAPER_INFERENCE_API_KEY"], base_url="https://api.cheaperinference.com/v1",)print(model.invoke("Hello").content)Codex
Send new local Codex tasks through Cheaper Inference's Responses API.
Official configuration reference
Supported: streamed responses, function calls, local Codex tools such as apply_patch, and usage accounting. This configuration applies to new local tasks in the Codex CLI, desktop app, and IDE extension. It does not change Codex cloud chats.
1. Install or verify Codex
If codex --version already prints a version, continue to step 2.
npm install --global @openai/codex codex --version
2. Make your API key available
Create a key in the Cheaper Inference dashboard. Replace the placeholder below, then run the command in the same terminal window you will use to start Codex. This sets the key for that terminal session only.
export CHEAPER_INFERENCE_API_KEY="ci_live_YOUR_API_KEY"
$env:CHEAPER_INFERENCE_API_KEY = "ci_live_YOUR_API_KEY"
3. Add the custom provider
Open ~/.codex/config.toml and add the configuration below. In the desktop app, choose Settings → Configuration → Open config.toml. Replace gpt-5.4 with any currently available text-model ID from the live catalog; models with reliable tool calling work best for coding tasks.
model = "gpt-5.4"model_provider = "cheaper-inference"[model_providers.cheaper-inference]name = "Cheaper Inference"base_url = "https://api.cheaperinference.com/v1"env_key = "CHEAPER_INFERENCE_API_KEY"wire_api = "responses"Using the macOS desktop app from the Dock?
Apps opened from the Dock may not inherit a key exported in Terminal. Store a dedicated key in macOS Keychain, then use Codex's command-backed authentication. Paste your key when prompted; it will not appear in the command itself.
read -s "CHEAPER_KEY?Paste your Cheaper Inference API key: "echosecurity add-generic-password -U -a codex -s cheaper-inference-codex -w "$CHEAPER_KEY"unset CHEAPER_KEYIn the provider configuration, remove the env_key line and add:
[model_providers.cheaper-inference.auth] command = "/usr/bin/security" args = ["find-generic-password", "-a", "codex", "-s", "cheaper-inference-codex", "-w"]
Use either env_key or the auth block, not both.
4. Restart and test
From the terminal where you set the key, open your project and run:
codex exec --model gpt-5.4 --sandbox read-only "Run pwd without changing files, then tell me the directory."
In the Codex desktop app:
- Completely quit and reopen the app.
- Start a new local task; an existing task keeps its original model.
- Ask:
Inspect this project without changing files and tell me its framework.
Confirm it worked: open the Cheaper Inference dashboard. The completed request should show the selected model, endpoint /v1/responses, token usage, and a settled charge.
Troubleshooting
codex: command not found- Open a new terminal after installation and run
codex --versionagain. - npm reports
EACCESor “permission denied” - Do not change system-folder permissions blindly. Use npm's recommended EACCES fix or install Codex through a user-managed Node installation.
- The request returns
401 - The process cannot read your API key. Start the CLI from the terminal where you exported it, or use the macOS Keychain option for the desktop app.
- The model is missing from the picker
- Custom models may not appear in Codex's built-in picker. Set the exact model ID in
config.toml, restart Codex, and begin a new local task. - Codex warns about unknown or fallback model metadata
- This warning can be non-blocking for a custom model. If the task completes and the dashboard records the request, the connection worked. Test tool use before relying on an unfamiliar model for larger coding tasks.
Responses API limitations
This endpoint is stateless and requires store: false. Stored responses, previous_response_id, conversations, background mode, and provider-hosted web or file search are not supported. Local Codex tools continue to work.
Claude Code
Run local Claude Code tasks through the Anthropic-compatible Messages API.
Available to all users: every Cheaper Inference account can connect Claude Code with an active API key that has Inference scope. No Anthropic account or separate enablement is required. Normal wallet balance, model access, and API-key limits still apply.
Supported: streamed text, local Claude Code tools, tool results, multi-turn tasks, vision input, token counting, and wallet usage accounting. This changes local Claude Code API traffic; it does not change claude.ai chats.
Compatibility scope: Claude Code uses POST /v1/messages and POST /v1/messages/count_tokens. This is not the complete Anthropic platform API; see the compatibility boundaries below.
Install or verify Claude Code:
npm install --global @anthropic-ai/claude-code claude --version
Create a key in the Cheaper Inference dashboard, then export the connection settings in the terminal that will launch Claude Code. Claude Code appends /v1/messages itself, so this base URL intentionally does not end in /v1.
export ANTHROPIC_BASE_URL="https://api.cheaperinference.com"export ANTHROPIC_AUTH_TOKEN="ci_live_YOUR_API_KEY"export ANTHROPIC_MODEL="claude-opus-4.8"export ANTHROPIC_SMALL_FAST_MODEL="claude-opus-4.8"claude --model claude-opus-4.8$env:ANTHROPIC_BASE_URL = "https://api.cheaperinference.com"$env:ANTHROPIC_AUTH_TOKEN = "ci_live_YOUR_API_KEY"$env:ANTHROPIC_MODEL = "claude-opus-4.8"$env:ANTHROPIC_SMALL_FAST_MODEL = "claude-opus-4.8"claude --model claude-opus-4.8Verify the connection
First verify the Messages endpoint independently of Claude Code. A successful response confirms the key, model ID, Anthropic request shape, routing, and wallet settlement.
curl https://api.cheaperinference.com/v1/messages \ -H "X-Api-Key: ci_live_YOUR_API_KEY" \ -H "Anthropic-Version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-opus-4.8", "max_tokens": 64, "messages": [{"role": "user", "content": "Reply with: connected"}] }'Then run one non-interactive Claude Code task from the configured terminal:
claude -p "Reply with: Claude Code connected" --model claude-opus-4.8
Expected result: Claude Code prints a response, and the dashboard shows a settled /v1/messages request with the selected model and token usage.
Model selection: replace both model values with an exact text-model ID from the live catalog. Setting the small/fast model explicitly prevents background helper calls from selecting an Anthropic model ID that is not in your workspace catalog.
Authentication: ANTHROPIC_AUTH_TOKEN sends the key as a bearer token. The Messages endpoint also accepts X-Api-Key for Anthropic SDK clients. Do not put a live key in a repository or shared settings file.
Messages API compatibility boundaries
Claude Code's local tools and multi-turn tool results are supported. Anthropic-hosted server tools, Message Batches, Files, and signed thinking-block replay are not supported. Extended-thinking settings can guide an eligible model, but responses do not expose Anthropic-signed thinking blocks. If Claude Code introduces a new Anthropic API feature, validate it against this guide before relying on it in production.
OpenClaw
Add Cheaper Inference as a custom Chat Completions provider.
- Set
CHEAPER_INFERENCE_API_KEYin the environment that starts OpenClaw. - Add the provider and model to your OpenClaw configuration.
- Select the model as
cheaper-inference/gpt-5.4.
{ "env": { "CHEAPER_INFERENCE_API_KEY": "ci_live_YOUR_API_KEY" }, "agents": { "defaults": { "model": { "primary": "cheaper-inference/gpt-5.4" } } }, "models": { "providers": { "cheaper-inference": { "baseUrl": "https://api.cheaperinference.com/v1", "apiKey": "${CHEAPER_INFERENCE_API_KEY}", "api": "openai-completions", "models": [ { "id": "gpt-5.4", "name": "GPT-5.4 via Cheaper Inference" } ] } } }}Important: keep api set to openai-completions. Add another object to models for each Cheaper Inference model ID you want OpenClaw to expose.
Capability metadata: OpenClaw supplies generic context, output-token, reasoning, and input-modality defaults when optional model fields are omitted. Add explicit values only after verifying them for the exact model you selected.
Hermes Agent
Use Hermes' custom endpoint option.
- Run
hermes model. - Choose Custom endpoint (self-hosted / VLLM / etc.).
- Enter the base URL above, your API key, and an exact model ID such as
gpt-5.4. - When Hermes asks for the API mode, choose Chat Completions.
For a manual setup, put CHEAPER_INFERENCE_API_KEY=ci_live_YOUR_API_KEY in ~/.hermes/.env, then edit ~/.hermes/config.yaml:
custom_providers: - name: cheaper-inference base_url: https://api.cheaperinference.com/v1 key_env: CHEAPER_INFERENCE_API_KEY api_mode: chat_completionsmodel: default: gpt-5.4 provider: custom:cheaper-inferenceRecommended: use hermes model so Hermes writes the configuration in its current format. Protect ~/.hermes/.env because it contains your key.
OpenCode
Configure an OpenAI-compatible custom provider.
- Open
/connect, choose Other, entercheaper-inference, and add your API key. - Add the provider below to
opencode.json, then use/modelsto select it.
{ "$schema": "https://opencode.ai/config.json", "provider": { "cheaper-inference": { "npm": "@ai-sdk/openai-compatible", "name": "Cheaper Inference", "options": { "baseURL": "https://api.cheaperinference.com/v1" }, "models": { "gpt-5.4": { "name": "GPT-5.4" } } } }}Important: use @ai-sdk/openai-compatible so OpenCode sends Chat Completions requests. Add more entries under models using exact IDs from the live catalog.
OpenWork
Use Cheaper Inference in the OpenCode-powered desktop agent.
The OpenCode schema is intentional: OpenWork uses OpenCode as its model engine and reads OpenCode provider configuration for each workspace.
- Open a workspace in OpenWork and create
opencode.jsonin that workspace's root folder. - Add the provider configuration below, then reopen or reload the workspace.
- Open Settings → AI Providers → Connect provider, choose Cheaper Inference, and paste your API key.
- Select a Cheaper Inference model from OpenWork's model picker and start a task.
{ "$schema": "https://opencode.ai/config.json", "provider": { "cheaper-inference": { "npm": "@ai-sdk/openai-compatible", "name": "Cheaper Inference", "env": ["CHEAPER_INFERENCE_API_KEY"], "options": { "baseURL": "https://api.cheaperinference.com/v1" }, "models": { "gpt-5.4": { "name": "GPT-5.4" }, "claude-opus-4.8": { "name": "Claude Opus 4.8" }, "deepseek-v4": { "name": "DeepSeek V4" } } } }}Keep the key out of the file: the env declaration tells OpenWork that this provider accepts an API key; it does not contain the secret. OpenWork stores the key locally through OpenCode after you connect the provider. Add or replace model entries using exact IDs from the live catalog.
If Cheaper Inference does not appear: completely reload the workspace engine after saving the file. If it is still missing, capture the exact error and your OpenWork version before contacting support.
Open WebUI
Connect a hosted or self-hosted chat interface.
- Open Admin Settings → Connections → OpenAI.
- Click Add Connection.
- Enter
https://api.cheaperinference.com/v1and your API key, then save. - Select a discovered model. If needed, add exact IDs under Model IDs (Filter).
Feature scope: chat and model discovery work through the Cheaper Inference connection. Configure a separate provider for Open WebUI features that require embeddings, speech-to-text, or text-to-speech.
Cline
Use the OpenAI Compatible provider in VS Code.
- Open Cline settings and choose OpenAI Compatible as the API provider.
- Set the Base URL to
https://api.cheaperinference.com/v1. - Paste your API key and enter an exact model ID such as
gpt-5.4. - Save, then start a small task and confirm the request appears in the Cheaper Inference dashboard.
Advanced model settings: enable image support, computer/tool use, and context or output limits only when the selected model supports them. These settings are model-specific, even when the same OpenAI-compatible connection is reused.
Cursor
Use Cursor's OpenAI base-URL override for compatible models.
Supported with limitations: Cursor can send Ask and Agent requests for OpenAI-family models through Cheaper Inference. The gateway bridges Cursor's streamed ApplyPatch custom tool and older Responses-shaped BYOK requests. Cursor controls the agent runtime and some specialized features separately, so this is not a replacement for every Cursor-hosted model or feature.
- Update Cursor to the latest stable version.
- Create a dedicated Cheaper Inference key with Inference scope. Limit it to the models Cursor should use, then add appropriate request and monthly-spend limits. Fund the wallet before verification if the workspace has no available balance.
- Open Cursor Settings → Models, then find OpenAI API Key.
- Paste the dedicated key and enable Override OpenAI Base URL.
- Set the base URL to
https://api.cheaperinference.com/v1, then click Verify. - Select an OpenAI-family model whose exact ID appears in the live model catalog.
- Test a short prompt in Ask mode, then ask Agent mode to inspect a file and make one harmless edit. Confirm each request appears in the Cheaper Inference dashboard with the expected model and a settled charge.
Global override: Cursor applies one OpenAI base URL and key across its OpenAI-family models; it cannot keep separate provider settings per custom model. Turn off the override when you want those models to use Cursor's normal routing again.
Key security: Cursor assembles requests through its service, so the gateway sees Cursor's outbound address rather than your workstation's address. Do not restrict the key to your workstation IP. If your organization has verified Cursor egress ranges, allow those ranges; otherwise rely on the dedicated key's model, rate, spend, expiry, and scope controls.
Model and feature scope: use the exact model ID Cursor forwards. If an ID already exists in Cursor, select that built-in entry instead of adding a duplicate. Claude- and Gemini-family IDs do not use Cursor's OpenAI override. Tab completion and other features that require specialized Cursor models continue to use Cursor's own infrastructure.
Compatibility path: Cursor sends these requests to /v1/chat/completions. Cheaper Inference accepts ordinary Ask requests, translates Agent's streamed ApplyPatch tool calls, and converts the older Responses-shaped BYOK format without changing the response shape Cursor expects.
Troubleshooting
- Cursor reports that key verification failed
- Confirm the key has Inference scope, is not expired, has access to the selected model, and the wallet has available balance. A workstation-only IP restriction will reject Cursor's server-side request.
- Ask works but Agent cannot edit a file
- Update Cursor, begin a new chat, and retry one small edit. Then use the request ID shown in the Cheaper Inference dashboard when contacting support; the gateway accepts both the current streamed
ApplyPatchshape and the older Responses-on-Chat shape. - Cursor's built-in model stops working
- The OpenAI base-URL override is global. Turn it off to return OpenAI-family models to Cursor's normal routing.
Aider
Point the terminal pair programmer at the compatible endpoint.
export OPENAI_API_BASE=https://api.cheaperinference.com/v1export OPENAI_API_KEY=ci_live_YOUR_API_KEYcd /path/to/your/projectaider --model openai/gpt-5.4$env:OPENAI_API_BASE = "https://api.cheaperinference.com/v1"$env:OPENAI_API_KEY = "ci_live_YOUR_API_KEY"Set-Location C:\path\to\your\projectaider --model openai/gpt-5.4Model naming: keep Aider's openai/ prefix, followed by the exact Cheaper Inference model ID. If Aider warns that a newer model is unknown, its official model settings can be used to describe the model's context and edit format.
LibreChat
Add a custom OpenAI-compatible endpoint for a team chat deployment.
Add the key to LibreChat's .env:
CHEAPER_INFERENCE_API_KEY=ci_live_YOUR_API_KEY
Add the endpoint to librechat.yaml, then restart LibreChat:
version: 1.3.13endpoints: custom: - name: Cheaper Inference apiKey: '${CHEAPER_INFERENCE_API_KEY}' baseURL: 'https://api.cheaperinference.com/v1' models: default: - gpt-5.4 - claude-opus-4.6 fetch: true titleConvo: true titleModel: gpt-5.4 modelDisplayLabel: Cheaper InferenceClaude model IDs: keep this as a custom OpenAI-compatible endpoint even when selecting a Claude model. Cheaper Inference translates the common request format to the serving provider.
Continue
Add a model to Continue's YAML configuration.
name: Cheaper Inferenceversion: 0.0.1schema: v1models: - name: GPT-5.4 through Cheaper Inference provider: openai model: gpt-5.4 apiBase: https://api.cheaperinference.com/v1 apiKey: ci_live_YOUR_API_KEY useResponsesApi: falseRecommended for Continue: keep useResponsesApi: false so Continue uses the broadly compatible Chat Completions path. The Responses endpoint is currently targeted at stateless Codex workloads.
Verify the connection
- Start with a short prompt and a model shown in the live catalog.
- Confirm the response completes in the app.
- Open your Cheaper Inference dashboard and verify the model, token usage, charge, and savings.
Codex can use /v1/responses, and Claude Code can use /v1/messages. For other apps, use OpenAI-compatible Chat Completions unless the guide says otherwise. Configure a separate provider for embeddings, audio, stored Responses conversations, or hosted web and file search. For raw HTTP examples, parameters, and error handling, see the API documentation.
Prompt cache and long-session savings
Every coding harness above bills long conversations by resending the full transcript on each turn. Anthropic and OpenAI both offer prompt caching so an unchanged prefix bills at cache-read rates instead of full input rates — the cache is where the discount lives on a long session.
What we measured on this deployment on 2026-08-18:
claude-opus-4.8(Claude Code, LibreChat’s Claude tab): 98.8% follow-up-turn hit rate over 15 turns, zero routing flips. Above the Opus break-even of 97.7%; realises the full advertised discount.gpt-5.6-sol(OpenWork, Open WebUI, Cursor): 98.3% over 15 turns.gpt-5.6-terra(OpenWork): 99.4% over 10 turns.deepseek-v4-flash(OpenWork): 98.3% over 10 turns.gpt-5.4on/v1/chat/completions(default recommendation for Cursor, Cline, Aider, Continue, Hermes, LibreChat, OpenClaw, OpenCode, Open WebUI): 77.3% over 15 turns, with one upstream account flip mid-conversation. Below the ideal ceiling for this model but the customer still saves ~47% per turn versus native OpenAI because our cache-read markup is deeper than list. If your session runs 20+ turns of cache-heavy replay, prefer a Claude model or one of the gpt-5.6 variants above.- Codex hits
/v1/responses, a stateless surface with different caching semantics from Chat Completions. We verified wire-shape works end-to-end ongpt-5.4,gpt-5-mini, andgpt-5.4-minithrough the Responses path, but the multi-turn cache measurement above does not translate directly — Codex sendsstore: falseon every call and replays its own transcript, so the cache lives inside a single request rather than across turns.
The scripts under scripts/verify-anthropic-cache-parity.mjs and scripts/verify-openai-cache-parity.mjs reproduce these numbers on demand.