Quick start
- Create an account.
- Add at least $5 to your wallet. On your first funding, we add $10 in bonus credit automatically.
- Create an API key from the dashboard and copy it once.
- Set the base URL for your SDK or app to the compatible endpoint below.
- Put a supported model name in the
modelfield. - Send your first request and review usage in the dashboard.
Using an AI app?
Use the step-by-step Codex guide for the Responses API, the Cursor guide for Ask and Agent, or the Claude Code guide for the Anthropic-compatible Messages API. The integration directory covers other supported apps.
OpenAI-compatible base URL
https://api.cheaperinference.com/v1
Anthropic-compatible base URL
https://api.cheaperinference.com
Anthropic SDKs and Claude Code append /v1/messages.
Authentication
Authorization: Bearer ci_live_YOUR_API_KEY
The Messages endpoints also accept X-Api-Key.
cURL chat completion
curl https://api.cheaperinference.com/v1/chat/completions \ -H "Authorization: Bearer ci_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-opus-4.6", "messages": [{"role": "user", "content": "Hello!"}] }'cURL Responses request
curl https://api.cheaperinference.com/v1/responses \ -H "Authorization: Bearer ci_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.4", "input": "Hello!", "store": false, "stream": true }'The stateless Responses compatibility layer supports Codex streaming, function calls, and custom local tools such as apply_patch. Requests must use store: false. Stored responses, previous_response_id, conversations, background mode, and provider-hosted web or file search are not supported.
Cursor compatibility
Cursor Ask and Agent can use OpenAI-family models through the OpenAI base-URL override. In Cursor Settings → Models, add a dedicated Cheaper Inference key, enable Override OpenAI Base URL, and enter https://api.cheaperinference.com/v1. Select an exact model ID from the live catalog, then verify both a short Ask prompt and one harmless Agent edit.
Cursor sends Agent tool traffic through Chat Completions. The gateway normalizes the current streamed ApplyPatch tool shape and the older Responses-shaped BYOK request format. Cursor's override is global for OpenAI-family models; tab completion, Claude- and Gemini-family models, and other Cursor-hosted features do not use this connection.
Use key scope, model, rate, spend, and expiration controls. Do not restrict the key to your workstation IP because Cursor sends these requests from its own service. See the complete Cursor setup and troubleshooting guide.
cURL Anthropic Messages request
Available to all users: every Cheaper Inference account can use these endpoints 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.
Compatibility scope: this integration implements POST /v1/messages and POST /v1/messages/count_tokens. It is not the complete Anthropic platform API; unsupported features are listed below.
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": 1024, "messages": [{"role": "user", "content": "Hello!"}] }'POST /v1/messages accepts the Anthropic Messages shape and returns an Anthropic-style message. It supports buffered and streamed text, system content, vision blocks, client-side tools and tool results, multi-turn replay, stop sequences, tool choice, usage accounting, and extended-thinking request hints. Streams use Anthropic event names such as message_start, content_block_delta, message_delta, and message_stop.
Use POST /v1/messages/count_tokens with the same model, system, messages, and tools fields for an estimated input_tokens count. Counting does not submit an inference request or charge the wallet.
Client-side tools work because Claude Code executes them locally and returns tool_result blocks. Anthropic-hosted server tools, Message Batches, Files, and signed thinking-block replay are not compatibility targets. Thinking settings can guide an eligible model, but responses do not expose Anthropic-signed thinking blocks.
For the complete environment setup and model mapping, use the Claude Code integration guide.
JavaScript SDK
import OpenAI from "openai";const client = new OpenAI({ apiKey: "ci_live_YOUR_API_KEY", baseURL: "https://api.cheaperinference.com/v1"});const response = await client.chat.completions.create({ model: "gpt-5.4", messages: [{ role: "user", content: "Hello!" }]});Python SDK
from openai import OpenAIclient = OpenAI( api_key="ci_live_YOUR_API_KEY", base_url="https://api.cheaperinference.com/v1",)response = client.chat.completions.create( model="claude-opus-4.6", messages=[{"role": "user", "content": "Hello!"}],)Anthropic Python SDK
from anthropic import Anthropicclient = Anthropic( api_key="ci_live_YOUR_API_KEY", base_url="https://api.cheaperinference.com",)message = client.messages.create( model="claude-opus-4.8", max_tokens=1024, messages=[{"role": "user", "content": "Hello!"}],)Parameters
OpenAI-compatible parameters
Chat requests use the OpenAI Chat Completions shape. Common fields such as temperature, top_p, max_tokens, max_completion_tokens, stop, tools, tool_choice, response_format, and reasoning are forwarded to the selected model.
Support and interpretation are model-specific. An unsupported parameter may be ignored or rejected by the serving provider, so test the exact model and request shape before moving production traffic.
Anthropic-compatible parameters
Messages requests accept model, messages, max_tokens, system, stream, temperature, top_p, stop_sequences, tools, tool_choice, and thinking. Use exact model IDs from GET /v1/models rather than Anthropic aliases.
Tools and structured output
Models that support tool calling accept the standard OpenAI tools and tool_choice fields. Models that support JSON output accept response_format, including json_object or a JSON schema where the model supports it.
"response_format": {
"type": "json_object"
}Images and vision
Vision input
Vision-capable chat models accept OpenAI image_url parts and Anthropic-style base64 image blocks. Check capabilities.vision in GET /v1/models before sending one.
Streaming
Models marked Streaming accept "stream": true on Messages, chat, text completion, and Responses endpoints. Streams use server-sent events, and wallet usage is settled when the stream completes. The gateway can retry and change routes before output begins. After the first event is delivered, a failed partial stream cannot be replaced transparently; retry the complete request.
Runnable vision request
Use an HTTPS image URL or a base64 data URL in an OpenAI image_url content part:
curl https://api.cheaperinference.com/v1/chat/completions \ -H "Authorization: Bearer ci_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.4", "messages": [{ "role": "user", "content": [ {"type": "text", "text": "Describe this image."}, { "type": "image_url", "image_url": {"url": "https://example.com/image.png"} } ] }] }'Prompt caching
cache_control is passed through when supported by the selected model. Cache reads and writes use imported model-specific rates when available. If no cache-read rate is available, cached reads use 10% of the normal input rate; cache writes without a separate rate use the normal input rate.
Available models and pricing
Copy the exact model ID into the model field. Every model we serve, with its current price and capabilities, is on the live model catalog. Each GET /v1/models item also includes an aliases array with the vendor-qualified id, including vendor-specific version punctuation, so migrations do not need a hand-maintained map. IDs absent from this catalog return HTTP 404.
How pricing and routing work
For every request, Cheaper Inference ranks the eligible provider routes by estimated cost and starts with the lowest-cost route available for that model and request. If that provider is unavailable, has insufficient capacity, or fails before output begins, the gateway automatically tries the next-lowest-cost eligible route. Your public model ID and API response format remain unchanged.
A fallback route can have a different rate from the first route. The final customer charge follows the route that successfully serves the request, but it will never exceed the model maker's applicable direct API list price. Cheaper Inference adds no separate routing surcharge; the settled API rate is all-in.
Provider prices can change over time. The exact amount charged for each completed request is available in your dashboard.
Model catalog API
Use your API key to retrieve currently available models and their current catalog rates. A fallback route can change the final rate for a request, subject to the direct-list-price ceiling above. Filter by type, vision, video, reasoning, streaming, or provider to find models that meet a workload's requirements.
curl 'https://api.cheaperinference.com/v1/models?type=text&vision=true&streaming=true' \ -H 'Authorization: Bearer ci_live_YOUR_API_KEY'
Token rates are USD per 1 million tokens. Fixed media rates use media_input_unit_price and media_unit_price per unit. For tiered models, use pricing.above_threshold when the request exceeds input_token_price_threshold.
Model prices do not change on a fixed customer-facing schedule: they can change when an upstream rate or an eligible route changes. Do not treat a locally cached rate as the final charge for a request. Use these response fields to validate a cache:
pricing_versionis a SHA-256 version of the returned, API-key-filtered catalog. An unchanged value means that catalog is unchanged.pricing_checked_atis the UTC time of the latest successful provider-price check.pricing_updated_atis the latest UTC catalog change among the returned models.
Pricing change feed
curl 'https://api.cheaperinference.com/v1/pricing/changes?since=2026-07-29T00:00:00Z' \ -H 'Authorization: Bearer ci_live_YOUR_API_KEY'
since is a required RFC 3339 timestamp. The endpoint returns the latest current customer-facing model object for each catalog row changed at or after that time. A removal has change_type: "removed" and model: null. Follow next_cursor while has_more is true; keep the original since value on every page.
{ "object": "pricing.changes", "pricing_version": "sha256:8f4c...", "pricing_checked_at": "2026-07-29T14:32:10Z", "pricing_updated_at": "2026-07-29T14:31:52Z", "data": [{ "model_id": "gpt-5.4", "change_type": "updated", "changed_at": "2026-07-29T14:31:52Z", "model": { "id": "gpt-5.4", "object": "model", "type": "text", "endpoint": "/v1/chat/completions", "pricing": { "currency": "USD", "input_per_million": "1.250000", "cache_read_input_per_million": "0.125000", "cache_write_input_per_million": "1.250000", "output_per_million": "10.000000" } } }], "has_more": false, "next_cursor": null}There is no pricing webhook at this time. Poll this feed, process changes idempotently by model_id and changed_at, then use the newest changed_at as the next since value. Because since is inclusive, the boundary change may be returned again. Periodically compare pricing_version with GET /v1/models to reconcile the full cache.
The catalog identifies modality, endpoint, vision, video, reasoning and streaming support. Tool calling, structured output, context limits, and accepted optional parameters can still vary by model and serving provider; verify the exact request shape before production use.
Reliability
Automatic retries and fallback
Network failures and HTTP 404, 408, 409, 425, 429, and 5xx responses are retried once. Other 4xx responses are not retried; when another route is eligible, the gateway immediately tries it in price order. Your request keeps the same public model ID and response format.
This failover happens automatically for provider capacity, availability, and transport failures. Validation, authentication, insufficient-balance, and oversized-payload errors still require a change from the caller.
Usage and response privacy
Successful responses include the model's token usage and a namespaced cheaper_inference object with the request ledger ID and exact settled customer charge. Streaming responses include this object in the protocol-specific final event. The request ID is also returned in the X-Cheaper-Inference-Request-Id header, and in x-ci-request-id. Provider cost and private routing metadata are removed before the response is returned to you.
{ "usage": { "prompt_tokens": 1234, "completion_tokens": 321, "total_tokens": 1555, "cost": 0.012345, "cost_details": { "upstream_inference_cost": 0.012345 } }, "cheaper_inference": { "request_id": 4812, "billing": { "status": "settled", "billed_cost_usd": "0.012345", "currency": "USD" } }}usage.cost and usage.cost_details.upstream_inference_cost both report the exact all-in customer charge after settlement. From the caller's perspective Cheaper Inference is the upstream inference service; the private amount paid to the selected serving provider is not exposed. cheaper_inference.billing.billed_cost_usd is the persisted amount deducted for that request after routing and settlement. For Chat Completions and Completions, streaming sends this metadata in a final empty-choice event immediately before [DONE]. Responses API streams include it in the final response.completed object. Messages streams include it on the final message_delta event. A failed or unsettled request does not report a billed amount.
Cheaper Inference does not store prompt or response bodies in its application database. Prompts are forwarded to the provider that serves the request, and provider-side handling is subject to that provider's applicable terms. Prompt caching may also create provider-side cached state. Request metadata needed for billing and operations is retained, including model, endpoint, token counts, charged amount, status, and a sanitized failure reason. Review the privacy policy for the full statement.
Usage and billing API
Usage reporting is workspace-wide and accepts the same API-key authentication as inference. Create a key with Usage reporting only access in API Keys when the reporting system should not be able to submit inference requests or spend wallet funds. Add api_key_id to restrict either endpoint to one key.
Request history
curl 'https://api.cheaperinference.com/v1/usage/requests?start_at=2026-07-01T00:00:00Z&end_at=2026-08-01T00:00:00Z&limit=100' \ -H 'Authorization: Bearer ci_live_YOUR_API_KEY'
start_atandend_atare optional RFC 3339 timestamps. The start is inclusive and the end is exclusive.api_key_idoptionally filters to a key owned by the same workspace.limitaccepts 1–100 and defaults to 100.cursoraccepts the previous page'snext_cursor. Results are newest first.
{ "object": "list", "scope": "workspace", "data": [{ "request_id": 4812, "api_key_id": 19, "api_key_name": "production", "model": "gpt-5.4", "endpoint": "/v1/chat/completions", "status": "settled", "prompt_tokens": 1234, "completion_tokens": 321, "cache_read_input_tokens": 0, "cache_write_input_tokens": 0, "total_tokens": 1555, "billed_cost_usd": "0.012345", "currency": "USD", "total_latency_ms": 1890, "time_to_first_token_ms": 420, "created_at": "2026-07-29T14:30:00Z", "completed_at": "2026-07-29T14:30:02Z" }], "has_more": false, "next_cursor": null}billed_cost_usd is non-null only when status is settled. Request history intentionally excludes prompts, generated content, provider cost, private route names, and profit or margin data.
Daily spend
curl 'https://api.cheaperinference.com/v1/usage/daily?start_at=2026-07-01T00:00:00Z&end_at=2026-08-01T00:00:00Z' \ -H 'Authorization: Bearer ci_live_YOUR_API_KEY'
- When dates are omitted, the endpoint returns the preceding 30 days through the current time.
- Every calendar date in the range is returned, including dates with zero requests.
{ "object": "usage.daily", "scope": "workspace", "currency": "USD", "start_at": "2026-07-01T00:00:00Z", "end_at": "2026-08-01T00:00:00Z", "total_requests": 820, "settled_requests": 811, "spend_usd": "148.420015", "daily_spend": [{ "date": "2026-06-30", "request_count": 24, "settled_request_count": 24, "spend_usd": "3.910042" }]}Daily spend sums persisted charges for settled requests only. Therefore, total_requests can be greater than settled_requests.
API-key access
inferencepermits inference requests.usage:readpermits request history, daily spend, and pricing-change reads.GET /v1/modelsaccepts any valid API key.- Use a reporting-only key for billing exports and monitoring systems.
Production checklist
- Load your API key from a server-side environment variable.
- Use
GET /v1/modelsto confirm the model is available and supports the required modality. - Set an explicit client timeout appropriate for long model generations.
- For direct HTTP clients, retry transport errors,
429, and5xxresponses with exponential backoff. - Do not retry
400,401,402, or413without correcting the request. For402, add funds before retrying. - Treat an interrupted stream as incomplete and retry the entire request.
- Review token usage, spend, and failures in the dashboard before increasing traffic.
For the generated public request, response, authentication, and error schemas, open the API reference.
Errors and limits
Billing and wallet
- Wallet balance is checked before a request starts.
- Usage is deducted after a completed request.
- Add funds manually or enable auto-recharge.
Security and keys
- Store API keys in environment variables, not frontend code.
- Create separate keys for production and testing.
- Configure model, IP, expiration, rate, concurrency, daily quota, and monthly budget controls from API Keys.
- Revoke exposed keys immediately.
Common errors
OpenAI-compatible endpoints use the envelope below. The Messages endpoints return Anthropic's {"type":"error","error":{...}} shape instead. Use the error type for program logic and keep the message for logs and operator context.
{ "error": { "message": "Invalid API key.", "type": "authentication_error", "param": null, "code": "invalid_api_key" }}400Unsupported model, endpoint, or invalid request body.401Invalid or missing API key.402/insufficient_balance: add funds in Billing, then retry the request.403The API key does not allow the model, client IP, or request.413Request body or vision payload is too large.422A query or typed request parameter failed validation.429A rate, concurrency, or quota limit was reached. Respect theRetry-Afterresponse header before retrying.502Provider or transport failure after eligible routes were exhausted.503No eligible provider route is currently available.504The serving provider timed out.