# OneProvider > Fast access to production AI models (Claude, GPT, Gemini, DeepSeek, Grok, Kimi, GLM, Qwen) through OpenAI-compatible and Anthropic-native APIs. The current list is in the catalog below and in `GET /v1/models`. Pay as you go via crypto, international cards / Apple Pay, or SBP/QR with one reusable balance. Full text with documentation in one file: `https://oneprovider.dev/llms-full.txt`. OneProvider operates `https://api.oneprovider.dev` as an Anthropic-compatible endpoint (`/v1/messages`, `/v1/messages/count_tokens`) and `https://api.oneprovider.dev/v1` as an OpenAI-compatible endpoint (`/v1/chat/completions`, `/v1/responses`, `/v1/images/generations`, `/v1/images/edits`). The same key works across text and image surfaces. Streaming (SSE) is supported on text-generation routes; image streaming is supported but has not been audited for every model. Keys are valid for 1 to 90 days depending on the key; user balance does not expire. Keys come from the customer's personal cabinet: the Telegram bot `@oneprovider_robot` (Account) or `https://app.oneprovider.dev` (sign in with Telegram, Google, or email and password). The customer tops up one shared balance (or activates a marketplace code `OP-XXXX-XXXX`: bot → Other → Activate code, site → Balance → OP code) and issues keys (3 by default; support can raise the limit), each with a name, an optional spend limit and a term of up to 90 days. An agent cannot create a key: ask the user to issue one and paste it, and never print or commit it. **Setting up a client? Fetch the full agent bundle first: `https://oneprovider.dev/docs/llms.txt`.** It has an agent playbook, exact settings files and environment variables for every client, and verification steps. ## Quick facts - What it is: a pay-as-you-go API gateway. One API key and one prepaid USD balance for Claude, GPT, Gemini, DeepSeek, Grok, Kimi, GLM and Qwen models. Not a subscription: no monthly fee, the balance does not expire (keys are valid for 1 to 90 days depending on the key, and can be extended). - Trademarks: Claude, GPT, Gemini and other model names are trademarks of their respective owners. - Operator and contacts: OneProvider Ltd, Nicosia, Cyprus; servers in Frankfurt (EU). [Contacts](https://oneprovider.dev/contact): support@oneprovider.dev, Telegram [@Oneproviderhelpbot](https://t.me/Oneproviderhelpbot). - Anthropic-native endpoint: `https://api.oneprovider.dev` (`POST /v1/messages`, `POST /v1/messages/count_tokens`). Use it as `ANTHROPIC_BASE_URL`, without `/v1`. - OpenAI-compatible endpoint: `https://api.oneprovider.dev/v1` (`/chat/completions`, `/responses`, `/images/generations`, `/images/edits`, `GET /models`). - Authentication: `x-api-key: sk-...` or `Authorization: Bearer sk-...`; the same key works on both endpoints. - Compatible clients: Claude Code (CLI, VS Code extension, Claude Desktop Code tab), Codex CLI, Cursor (GPT model IDs only), Cline, OpenCode, Hermes Agent, OpenClaw, Open Cowork, Factory Droid, n8n, TypingMind, the official `anthropic` and `openai` Python and Node SDKs, and any app with a custom OpenAI endpoint. - Pricing: pay per token at the per-1M-token USD rates in the catalog below and on [Pricing](https://oneprovider.dev/pricing); the cache discount is explained in [Token counting](https://oneprovider.dev/docs/pricing/tokens). The price of a top-up pack is shown in the cabinet before payment. - Payment methods: crypto (Telegram wallets), cards of any country with Apple Pay / Google Pay (Russian bank cards are not accepted by this channel), SBP/QR in rubles. Marketplace codes `OP-XXXX-XXXX` also top up the balance. Fees are shown before payment: SBP/QR 3.5% paid by the customer, crypto 3% provider fee plus the network fee. Details: [Payment methods](https://oneprovider.dev/legal/payment-methods), [Refund policy](https://oneprovider.dev/legal/refund). - Cabinet: the Telegram bot `@oneprovider_robot` or `https://app.oneprovider.dev` (sign in with Telegram, Google, or email and password): one balance, 3 keys by default, each with a name, an optional spend limit and a term, usage statistics. - Support: [@Oneproviderhelpbot](https://t.me/Oneproviderhelpbot) on Telegram, or the support chat in the cabinet. - Availability: no geoblocking and no VPN needed on the user's side; edge in EU (Frankfurt), TLS 1.3; live status at [Status](https://oneprovider.dev/status). Prompt bodies are not used as a marketing or analytics dataset: [Security](https://oneprovider.dev/security), [Privacy](https://oneprovider.dev/legal/privacy). - Languages: the site and documentation are in English and Russian (`/ru`). ## Common questions, short answers - **How do I use Claude Code with an API key instead of a Claude login?** Set `ANTHROPIC_BASE_URL=https://api.oneprovider.dev` and `ANTHROPIC_AUTH_TOKEN=` (or the `env` block of `~/.claude/settings.json`) and run `claude`. Guide: [Claude Code](https://oneprovider.dev/docs/clients/claude-code). - **Can one key use Claude and GPT?** Yes. One key and one balance work on the Anthropic-native endpoint (Claude) and on the OpenAI-compatible endpoint (GPT and the other catalog models). Cursor can override only the OpenAI base URL, so there it takes GPT model IDs. - **Is this an OpenRouter-style alternative?** It is a gateway of the same kind: one key, many model families, pay as you go. Facts that set it apart: a native Anthropic Messages endpoint with `count_tokens` for Claude Code, one USD balance shared by all keys with per-key spend limits, and top-ups by SBP/QR, crypto or cards of any country. Model IDs and rates are in the catalog below. - **What does Claude Opus or Sonnet cost through the API?** The per-1M-token input and output rates of every model are in the catalog table below and on [Pricing](https://oneprovider.dev/pricing). - **How do I migrate existing code?** Change only the base URL and the key: [from OpenAI](https://oneprovider.dev/docs/guides/migrate-from-openai), [from Anthropic](https://oneprovider.dev/docs/guides/migrate-from-anthropic). - **How do I get a key?** Open the cabinet, top up the balance, press Issue a key: [Cabinet & keys](https://oneprovider.dev/docs/first-key). An agent cannot create a key for the user. ## Cabinet settings - Sign-in: the web cabinet accepts Telegram, Google, or email and password. One person can have several (Settings → Profile and sign-in); the last one cannot be unlinked. - Change email: Settings → Profile and sign-in → Email row → Change email. Enter the new address and a password, then open the letter sent to the new address (the link is valid for 24 hours) while signed in. The new login replaces the old one and other browsers are signed out. The old mailbox is not needed if you can sign in with Telegram or Google; an address that belongs to another cabinet is refused. A forgotten password: Send a reset link, in the same row. - Referrals: Balance → Referrals tab: a link for the website and one for the bot, the invited people and what they brought, and Move to balance. ## По-русски (кратко) - OneProvider: API-шлюз с оплатой по факту использования. Один ключ и один баланс в USD для моделей Claude, GPT, Gemini, DeepSeek и других; без подписки, баланс не сгорает. - Один ключ к Claude и GPT: Anthropic-совместимый эндпоинт `https://api.oneprovider.dev` (для Claude Code, `ANTHROPIC_BASE_URL`) и OpenAI-совместимый `https://api.oneprovider.dev/v1`. - Цены за 1M токенов (в том числе Claude Opus и Sonnet): таблица каталога ниже и страница [Тарифы](https://oneprovider.dev/ru/pricing). - Оплата: СБП или QR в рублях, карты любой страны с Apple Pay и Google Pay (карты российских банков этим способом не принимаются), криптовалюта. VPN с вашей стороны не нужен. - Личный кабинет: бот `@oneprovider_robot` или `https://app.oneprovider.dev`. Поддержка: [@Oneproviderhelpbot](https://t.me/Oneproviderhelpbot). - Настройки кабинета: «Настройки» → «Профиль и вход» (Telegram, Google или почта и пароль); «Сменить почту»: письмо уходит на новый адрес, доступ к старой почте не нужен, если есть вход через Telegram или Google. Рефералы: «Баланс» → «Рефералы». - Инструкции: [Claude Code в России](https://oneprovider.dev/ru/claude-code-v-rossii), [Claude API в России](https://oneprovider.dev/ru/claude-api-v-rossii), [оплата через СБП](https://oneprovider.dev/ru/oplata-claude-sbp), [ChatGPT API](https://oneprovider.dev/ru/chatgpt-api-v-rossii). --- # OneProvider — Developer Documentation Bundle > Single-file documentation bundle for AI agents. Fetch this URL and you have everything needed to configure an Anthropic-compatible or OpenAI-compatible client against OneProvider. No external fetches required. Generated from catalog revision 2026-11-17.3. OneProvider is an API for the production AI model catalog. One API key works against Anthropic-native `/v1/messages`, OpenAI-shape `/v1/chat/completions` and `/v1/responses`, and the OpenAI Images API. Streaming (SSE) is supported on text-generation routes. Keys are valid for 1 to 90 days depending on the key; user balance does not expire. Balance and keys live in a personal cabinet, available in the Telegram bot `@oneprovider_robot` and on the web at `https://app.oneprovider.dev` (sign in with Telegram, Google, or email and password). Customers issue their own keys there; there is no separate "buy a key" step. - Anthropic SDK base URL: `https://api.oneprovider.dev` - OpenAI-compatible and Cursor Base URL: `https://api.oneprovider.dev/v1` - Public site: `https://oneprovider.dev` - Personal cabinet: `https://app.oneprovider.dev` on the web and `@oneprovider_robot` on Telegram - Support: `@Oneproviderhelpbot` on Telegram or the support chat in the web cabinet --- ## 0. Agent playbook (read this first) Goal: connect the user's client to OneProvider. Do these steps in order. 1. **The user brings the key.** An API key comes from the user's personal cabinet and you cannot create it for them. Ask them to open the cabinet (Telegram bot `@oneprovider_robot` → Account, or `https://app.oneprovider.dev`), top up the balance if it is empty (or activate a marketplace code `OP-XXXX-XXXX`: bot → Other → Activate code, site → Balance → OP code), press **Issue a key** (give it a name and a spend limit), and paste the key (`sk-` + 64 hex characters). 2. **Never print, log or commit the key.** Put it only where the client's section in §5 says: an environment variable or the client's own settings file. Do not write it into files that are committed to git. 3. **Pick the client section in §5** and use the right base URL form. Anthropic-style clients use `https://api.oneprovider.dev` (no `/v1`: the client appends `/v1/messages` itself). OpenAI-style clients use `https://api.oneprovider.dev/v1`. The wrong form returns 404 (a doubled `/v1` in the request path). 4. **Choose a model ID from §3**, or call `GET https://api.oneprovider.dev/v1/models` with the key. Never invent IDs. 5. **Write the config, then restart the client.** Most clients read their settings only at startup, and desktop apps must be fully quit and reopened. Existing sessions keep the old settings; start a new session or task. 6. **Verify.** (a) `curl -s https://api.oneprovider.dev/v1/models -H "Authorization: Bearer $ONEPROVIDER_KEY"` returns `200` and a model list; (b) run the verification step in the client's section; (c) the request appears in the cabinet under Usage with the model, tokens and charge. 7. **On an error**, use the table in §8: `401` wrong or disabled key; `403 API key expired` extend the key or issue a new one in the cabinet; `429 insufficient_balance` top up the cabinet or raise the key's limit; `404` wrong base URL form. --- ## 1. Endpoints (verified live) | Endpoint | Method | Schema | Notes | |----------------------------------------------|--------|-----------------------|----------------------------------------| | `/v1/messages` | POST | Anthropic Messages | Native Anthropic Messages format. | | `/v1/messages/count_tokens` | POST | Anthropic count_tokens| Returns `{"input_tokens": N}`. Free. | | `/v1/chat/completions` | POST | OpenAI Chat Completions | OpenAI Chat Completions format. | | `/v1/responses` | POST | OpenAI Responses | OpenAI Responses format (used by Codex). | | `/v1/images/generations` | POST | GPT Image 2 generation | JSON request; `b64_json` is production-validated. | | `/v1/images/edits` | POST | GPT Image 2 edits | Multipart request with image + prompt. | | `/v1/models` | GET | Model list | `401` without a key, `200` with the model list. | | `/v1/dashboard/balance` | GET | Balance | Returns the key's balance. OpenAI-style `/v1/dashboard/billing/*` paths also work. Auth via `Authorization: Bearer` (`x-api-key` works too). | `GET /v1/models` is the cheapest liveness and auth check. To check balance programmatically, call `GET /v1/dashboard/balance` (see §10.1). ## 2. Authentication Send the key on every request. Either header works on every endpoint: ``` x-api-key: sk-... ``` or ``` Authorization: Bearer sk-... ``` Keys look like `sk-` + 64 hex characters (67 chars total). ### 2.1 Where keys come from: the personal cabinet - Open the cabinet in the Telegram bot `@oneprovider_robot` (Account) or on the web at `https://app.oneprovider.dev`. Both show the same cabinet. Web sign-in: Telegram, Google, or email and password. Old keys move into the cabinet, with their balance, when the user opens the bot. - One shared balance; 3 keys by default (support can raise the limit). Each key has a name, an optional spend limit and a term (up to 90 days, extendable). Create, pause, extend and delete keys in the cabinet. - Top up in the cabinet: pack or custom amounts from $100 to $5000; crypto, international cards / Apple Pay / Google Pay, or SBP/QR. A marketplace code `OP-XXXX-XXXX` is activated in the bot (Other → Activate code) or on the site (Balance → OP code) and goes to the same balance. - The full key is shown once when issued; later only via Reveal after a fresh sign-in. A leaked key: delete it in the cabinet and issue a new one; the balance stays in the cabinet. - Bonuses (welcome, first top-up) are promotional offers: they can expire, cannot be withdrawn and are not refundable. The cabinet has a Referrals tab with a personal invite link. Two cabinets of one person (for example Telegram and web) can be merged through `@Oneproviderhelpbot` after ownership is confirmed. - Cabinet sign-in is separate from API authentication: the API key remains the bearer credential for API requests. Keys outside a cabinet are revoked through `@Oneproviderhelpbot`. ## 3. Model IDs This block is generated from the public model catalog. It lists current advertised IDs; compatibility IDs may remain routable without being advertised here. ### Claude models (Anthropic-native) | Canonical ID | Name | Tier | Context | Max output | Input / 1M | Output / 1M | |---|---|---:|---:|---:|---:|---:| | `claude-fable-5` | Claude Fable 5 | frontier | 1M | — | $10.00 | $50.00 | | `claude-haiku-4-5` | Claude Haiku 4.5 | speed | 200K | 64K | $1.00 | $5.00 | | `claude-haiku-4-5-20251001` | Claude Haiku 4.5 20251001 | speed | 200K | 64K | $1.00 | $5.00 | | `claude-haiku-4-5-20251001-thinking` | Claude Haiku 4.5 20251001 Thinking | speed | — | — | $1.00 | $5.00 | | `claude-haiku-4-5-thinking` | Claude Haiku 4.5 Thinking | speed | — | — | $1.00 | $5.00 | | `claude-opus-4-6` | Claude Opus 4.6 | frontier | 1M | 128K | $5.00 | $25.00 | | `claude-opus-4-7` | Claude Opus 4.7 | frontier | 1M | 128K | $5.00 | $25.00 | | `claude-opus-4-8` | Claude Opus 4.8 | flagship | 1M | 128K | $5.00 | $25.00 | | `claude-opus-5` | Claude Opus 5 | flagship | 1M | 128K | $5.00 | $25.00 | | `claude-opus-5-5` | Claude Opus 5.5 | flagship | 1M | 128K | $4.00 | $20.00 | | `claude-sonnet-5-5` | Claude Sonnet 5.5 | balanced | 1M | — | $2.00 | $10.00 | | `claude-haiku-5-5` | Claude Haiku 5.5 | speed | 1M | 128K | $0.10 | $0.50 | | `claude-opus-5-thinking` | Claude Opus 5 Thinking | frontier | — | — | $5.00 | $25.00 | | `claude-sonnet-4-6` | Claude Sonnet 4.6 | balanced | 1M | 64K | $3.00 | $15.00 | | `claude-sonnet-5` | Claude Sonnet 5 | balanced | 1M | — | $2.00 | $10.00 | | `claude-sonnet-5-thinking` | Claude Sonnet 5 Thinking | frontier | 1M | — | $2.00 | $10.00 | | `claude-fable-5-1` | Claude Fable 5.1 | frontier | 1M | — | $10.00 | $50.00 | ### GPT models (OpenAI-compatible) | Canonical ID | Name | Tier | Context | Max output | Input / 1M | Output / 1M | |---|---|---:|---:|---:|---:|---:| | `deepseek-v4.1-flash-1017` | DeepSeek V4.1 Flash 1017 | speed | 1M | 393,216 | $0.30 | $1.20 | | `deepseek-v4.1-flash` | DeepSeek V4.1 Flash | speed | 1M | 393,216 | $0.30 | $1.20 | | `deepseek-v4-flash` | DeepSeek V4 Flash | speed | 1M | 393,216 | $0.30 | $1.20 | | `deepseek-v4-flash-0731` | DeepSeek V4 Flash 0731 | speed | 1M | 393,216 | $0.30 | $1.20 | | `deepseek-v4-flash-vision-exp` | DeepSeek V4 Flash Vision Exp | speed | 1M | 393,216 | $0.30 | $1.20 | | `deepseek-v4-pro` | DeepSeek V4 Pro | frontier | 1M | 393,216 | $1.32 | $3.96 | | `deepseek-v4-pro-0813` | DeepSeek V4 Pro 0813 | frontier | 1M | 393,216 | $1.32 | $3.96 | | `gemini-3.1-flash-image` | Gemini 3.1 Flash Image | image | 131,072 | 32,768 | — | — | | `gemini-3.5-flash` | Gemini 3.5 Flash | balanced | 1.049M | 65,536 | $1.50 | $9.00 | | `gemini-3.6-flash` | Gemini 3.6 Flash | speed | 1.049M | 65,536 | $0.75 | $3.75 | | `gemini-3.6-flash-tiered` | Gemini 3.6 Flash Tiered | speed | 1.049M | 65,536 | $0.75 | $3.75 | | `gemini-3.8-flash` | Gemini 3.8 Flash | speed | 1.049M | 65,536 | $0.75 | $3.75 | | `gemini-4-argon` | Gemini 4 Argon | frontier | 1.049M | 65,536 | $2.00 | $10.00 | | `gemini-4-carbon` | Gemini 4 Carbon | frontier | 1.049M | 65,536 | $2.00 | $10.00 | | `gemini-4-hydrogen` | Gemini 4 Hydrogen | speed | 1.049M | 65,536 | $1.50 | $7.50 | | `glm-5.3` | GLM 5.3 | frontier | 1M | 131,072 | $1.40 | $4.40 | | `glm-5.3-flash` | GLM 5.3 Flash | speed | 1.049M | 131,072 | $0.15 | $0.50 | | `glm-5.2` | GLM 5.2 | frontier | 1M | 131,072 | $1.40 | $4.40 | | `gpt-6.1-sol` | GPT-6.1 Sol | frontier | 1.05M | 128K | $2.00 | $10.00 | | `gpt-6.1-terra` | GPT-6.1 Terra | balanced | 1.05M | 128K | $1.00 | $5.00 | | `gpt-6-astra` | GPT-6 Astra | frontier | 1.1M | 128K | $10.00 | $50.00 | | `gpt-6-sol` | GPT-6 Sol | frontier | 1.05M | 128K | $2.00 | $10.00 | | `gpt-5.5` | GPT-5.5 | flagship | 1.05M | 128K | $5.00 | $30.00 | | `gpt-5.6-luna` | GPT-5.6 Luna | efficient | 1.05M | 128K | $1.00 | $6.00 | | `gpt-5.6-sol` | GPT-5.6 Sol | frontier | 1.05M | 128K | $5.00 | $30.00 | | `gpt-5.6-terra` | GPT-5.6 Terra | balanced | 1.05M | 128K | $2.50 | $15.00 | | `gpt-6-luna` | GPT-6 Luna | efficient | 1.05M | 128K | $0.10 | $0.50 | | `gpt-image-2` | GPT Image 2 | image | — | — | $5.00 | $10.00 | | `gpt-image-2.5-flare` | GPT Image 2.5 Flare | image | — | — | $5.00 | $10.00 | | `gpt-image-2.5-sunburst` | GPT Image 2.5 Sunburst | image | — | — | $5.00 | $10.00 | | `gpt-image-2.6-flare` | GPT Image 2.6 Flare | image | — | — | $5.00 | $10.00 | | `gpt-image-2.6-sunburst` | GPT Image 2.6 Sunburst | image | — | — | $5.00 | $10.00 | | `grok-4.5` | Grok 4.5 | flagship | 500K | — | $2.00 | $6.00 | | `grok-4.6` | Grok 4.6 | frontier | 500K | — | $2.00 | $6.00 | | `grok-4.7` | Grok 4.7 | frontier | 500K | — | $2.00 | $6.00 | | `grok-imagine` | Grok Imagine | image | — | — | — | — | | `grok-imagine-image` | Grok Imagine Image | image | — | — | — | — | | `grok-imagine-image-lite` | Grok Imagine Image Lite | image | — | — | — | — | | `kling-3.0` | Kling 3.0 | video | — | — | — | — | | `grok-tts` | Grok TTS | audio | — | — | — | — | | `grok-stt` | Grok STT | audio | — | — | — | — | | `grok-voice-3.0` | Grok Voice 3.0 | audio | — | — | — | — | | `grok-voice-latest` | Grok Voice (latest) | audio | — | — | — | — | | `gemini-2.5-flash-tts` | Gemini 2.5 Flash TTS | audio | — | — | — | — | | `gemini-2.5-pro-tts` | Gemini 2.5 Pro TTS | audio | — | — | — | — | | `gemini-3.1-flash-tts` | Gemini 3.1 Flash TTS | audio | — | — | — | — | | `gemini-3.1-tts` | Gemini 3.1 TTS | audio | — | — | — | — | | `gemini-3.8-flash-tts` | Gemini 3.8 Flash TTS | audio | — | — | — | — | | `gemini-3.8-flash-lite-tts` | Gemini 3.8 Flash-Lite TTS | audio | — | — | — | — | | `gemini-3.5-transcribe` | Gemini 3.5 Transcribe | audio | — | — | — | — | | `gemini-3.5-stt` | Gemini 3.5 STT | audio | — | — | — | — | | `gemini-3-stt` | Gemini 3 STT | audio | — | — | — | — | | `kimi-k2.7-code` | Kimi K2.7 Code | balanced | 262,144 | — | $0.95 | $4.00 | | `kimi-k3` | Kimi K3 | frontier | 1.049M | — | $3.00 | $15.00 | | `kimi-k3.1-pro` | Kimi K3.1 Pro | frontier | 1.049M | — | $2.00 | $10.00 | | `gemini-3-pro-image` | Gemini 3 Pro Image | image | — | — | $2.00 | $12.00 | | `gemini-3-pro-image-preview` | Gemini 3 Pro Image Preview | image | — | — | $2.00 | $12.00 | | `gemini-3.1-flash-image-preview` | Gemini 3.1 Flash Image Preview | image | 131,072 | 32,768 | $0.50 | $3.00 | | `glm-5.1` | GLM 5.1 | flagship | — | — | $1.40 | $4.40 | | `qwen3.7-max` | Qwen 3.7 Max | frontier | — | — | $1.65 | $4.951 | | `qwen3.7-plus` | Qwen 3.7 Plus | balanced | — | — | $0.40 | $1.60 | | `qwen3.8-flash` | Qwen 3.8 Flash | speed | — | — | $0.15 | $0.47 | | `qwen3.8-max` | Qwen 3.8 Max | frontier | — | — | $1.65 | $4.951 | | `minimax-m3` | MiniMax M3 | frontier | 1M | — | $0.30 | $1.20 | | `minimax-m3.1-flash` | MiniMax M3.1 Flash | speed | 1M | — | $0.15 | $0.60 | | `minimax-m2.7` | MiniMax M2.7 | balanced | 204,800 | — | $0.30 | $1.20 | | `mimo-v2.6-pro` | MiMo V2.6 Pro | frontier | 1.049M | 131,072 | $0.435 | $0.87 | | `mimo-v2.6-flash` | MiMo V2.6 Flash | speed | 1.049M | 131,072 | $0.14 | $0.28 | Free-form Claude spellings and documented capability suffixes are normalized server-side before forwarding. Compatibility model IDs may remain routable even when they are not advertised in the current catalog. ## 4. Quickstart ### 4.1 curl — Anthropic-native ```bash export ANTHROPIC_API_KEY=sk-your-key-here export ANTHROPIC_BASE_URL=https://api.oneprovider.dev curl -s "$ANTHROPIC_BASE_URL/v1/messages" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 64, "messages": [{"role":"user","content":"ping"}] }' ``` ### 4.2 curl — OpenAI-compatible ```bash export OPENAI_API_KEY=sk-your-key-here export OPENAI_BASE_URL="https://api.oneprovider.dev/v1" curl -s "$OPENAI_BASE_URL/chat/completions" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 64, "messages": [{"role":"user","content":"ping"}] }' ``` ### 4.3 Python — anthropic SDK ```python import os, anthropic client = anthropic.Anthropic( api_key=os.environ["ANTHROPIC_API_KEY"], base_url="https://api.oneprovider.dev", ) msg = client.messages.create( model="claude-sonnet-5-5", max_tokens=256, messages=[{"role":"user","content":"ping"}], ) # a thinking block can come first: print the text blocks print("".join(b.text for b in msg.content if b.type == "text")) ``` ### 4.4 Python — openai SDK ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ["ANTHROPIC_API_KEY"], base_url="https://api.oneprovider.dev/v1", ) resp = client.chat.completions.create( model="claude-sonnet-5-5", max_tokens=64, messages=[{"role":"user","content":"ping"}], ) print(resp.choices[0].message.content) ``` ### 4.5 Node — @anthropic-ai/sdk ```javascript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, baseURL: "https://api.oneprovider.dev", }); const msg = await client.messages.create({ model: "claude-sonnet-5-5", max_tokens: 256, messages: [{ role: "user", content: "ping" }], }); // a thinking block can come first: print the text blocks for (const block of msg.content) if (block.type === "text") console.log(block.text); ``` ### 4.6 Node — openai ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.ANTHROPIC_API_KEY, baseURL: "https://api.oneprovider.dev/v1", }); const r = await client.chat.completions.create({ model: "claude-sonnet-5-5", max_tokens: 64, messages: [{ role: "user", content: "ping" }], }); console.log(r.choices[0].message.content); ``` ### 4.7 Image generation ```bash curl -sS https://api.oneprovider.dev/v1/images/generations \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "A cobalt-blue ceramic teapot on a neutral studio background", "size": "1024x1024", "quality": "low" }' ``` Read the returned image payload according to the response shape of the selected verified transport. For edits, send multipart form data to `/v1/images/edits` with `model`, `prompt`, and an `image` file; do not inject optional fields that are absent from the model contract. Pricing is **$8.00 / 1M image input tokens**, **$2.00 / 1M cached image input tokens**, and **$30.00 / 1M image output tokens**; calculate final cost from the response's actual `usage` rather than treating a sample token count as typical. Full guide: `https://oneprovider.dev/docs/guides/image-generation`. ## 5. Client setup Every client below needs the same two things: a key from the cabinet (§0, §2.1) and the right base URL form. Anthropic-style clients: `https://api.oneprovider.dev`. OpenAI-style clients: `https://api.oneprovider.dev/v1`. Human-readable guides: `https://oneprovider.dev/docs` (one page per client under `/docs/clients/`). | Client | Base URL | Where the settings live | Section | |---|---|---|---| | Claude Code (CLI) | `https://api.oneprovider.dev` | `~/.claude/settings.json` (`env` block) or shell env | 5.1 | | Claude Desktop (Code tab) | `https://api.oneprovider.dev` | Developer → Configure Third-Party Inference (app UI) | 5.2 | | VS Code (Claude Code extension) | `https://api.oneprovider.dev` | `~/.claude/settings.json` and VS Code user settings | 5.3 | | Codex (CLI, desktop, IDE) | `https://api.oneprovider.dev/v1` | `~/.codex/config.toml` | 5.4 | | Cursor | `https://api.oneprovider.dev/v1` | Settings → Models → API Keys | 5.5 | | Cline | `https://api.oneprovider.dev/v1` | Cline API Provider settings (OpenAI Compatible) | 5.6 | | Hermes Agent | `https://api.oneprovider.dev/v1` | `~/.hermes/config.yaml` and `~/.hermes/.env` | 5.7 | | OpenCode | `https://api.oneprovider.dev/v1` | `~/.config/opencode/opencode.json` | 5.8 | | OpenClaw | `https://api.oneprovider.dev` | `~/.openclaw/openclaw.json` | 5.9 | | Open Cowork | `https://api.oneprovider.dev` | Settings → API Settings (app UI) | 5.10 | | Factory Droid | `https://api.oneprovider.dev` | `~/.factory/settings.json` | 5.11 | | n8n | `https://api.oneprovider.dev/v1` | HTTP Request node + Header Auth credential | 5.12 | | Other OpenAI-compatible apps | `https://api.oneprovider.dev/v1` | the app's "custom OpenAI endpoint" settings | 5.13 | | TypingMind | `https://api.oneprovider.dev/v1/messages` | Models → Add custom model; the FULL endpoint (`/v1/messages` or `/v1/chat/completions`), not a base URL | 5.15 | On Windows, `~` means `%USERPROFILE%`. Settings files are plain JSON/TOML/YAML: keep them valid (no smart quotes from chat apps) and restart the client after editing. ### 5.1 Claude Code (Anthropic CLI) Install: `npm install -g @anthropic-ai/claude-code` (needs Node.js 22+; the package is `@anthropic-ai/claude-code`, not `@anthropic-ai/claude`), then run `claude`. Settings file: `~/.claude/settings.json` (macOS, Linux) or `%USERPROFILE%\.claude\settings.json` (Windows). Create it if it does not exist: ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.oneprovider.dev", "ANTHROPIC_AUTH_TOKEN": "sk-your-key-here" }, "model": "claude-sonnet-5-5" } ``` Per session, without the file: the key is typed at a hidden prompt, never a literal in history. macOS/Linux: `export ANTHROPIC_BASE_URL='https://api.oneprovider.dev'`, then zsh `read -rs 'ANTHROPIC_AUTH_TOKEN?API key: '` or bash `IFS= read -r -s -p 'API key: ' ANTHROPIC_AUTH_TOKEN`. PowerShell: `$env:ANTHROPIC_BASE_URL = 'https://api.oneprovider.dev'` and `$secure = Read-Host 'API key' -AsSecureString` then `$env:ANTHROPIC_AUTH_TOKEN = [System.Net.NetworkCredential]::new('', $secure).Password`. Run `claude` from the same terminal; never publish the real key in chat, commands or screenshots. `ANTHROPIC_AUTH_TOKEN` is sent as `Authorization: Bearer`, takes precedence over a saved claude.ai login and needs no approval prompt; `ANTHROPIC_API_KEY` (`x-api-key`) also works but Claude Code asks once to approve it and silently ignores a declined key. If Claude Code shows an Auth conflict warning or the login screen because of a saved claude.ai login, run `/logout` inside Claude Code; do not unset `ANTHROPIC_AUTH_TOKEN`. Set `model` to a canonical active Claude ID from §3. Client-only capability suffixes such as `[1m]` and `[200k]` are not separate catalog entries; use the canonical ID and the documented request headers for optional capabilities. Verify configuration and connectivity separately — three different checks. Config parses: `jq -e . ~/.claude/settings.json >/dev/null` (PowerShell: `Get-Content $HOME\.claude\settings.json -Raw | ConvertFrom-Json | Out-Null`). Endpoint reachable, no credentials needed: `curl -sS -o /dev/null -w '%{http_code}\n' https://api.oneprovider.dev/v1/models` (PowerShell: `curl.exe -sS -o NUL -w "%{http_code}\n" https://api.oneprovider.dev/v1/models`); a 401/403 reply still proves reachability but not that the client loaded the key. Client works end to end: `claude -p "say hi in one sentence"`, then `/status` for the configured base URL. `/v1/messages/count_tokens` returns 200 OK with an estimate (about one token per 4 characters), so Claude Code's startup probe will not fail. ### 5.2 Claude Desktop (Code tab) The Code tab of the Claude Desktop app (and Cowork) can run on OneProvider without a Claude account through the app's built-in gateway mode (Anthropic calls it third-party inference). Desktop takes the gateway from its own form, not from `ANTHROPIC_BASE_URL` or `~/.claude/settings.json`. These are UI steps, so give them to the user: 1. Install Claude Desktop (macOS 14+, or Windows 10 version 2004 and newer including Windows 11) from the official Claude site. Launch it and stay on the sign-in screen; do not sign in. 2. Turn on Developer Mode. macOS: menu bar Help → Troubleshooting → Enable Developer Mode. Windows: application menu ☰ at the top-left of the sign-in screen → Help → Troubleshooting → Enable Developer Mode. The app restarts and a Developer menu appears. 3. Developer → Configure Third-Party Inference…, section Connection: set Inference provider to `Gateway`, Gateway base URL to `https://api.oneprovider.dev` (no `/v1`, no path), Gateway API key to the OneProvider key, Credential kind `Static API key`, Gateway auth scheme `Bearer` (`x-api-key` also works). 4. Leave Models empty first: Desktop calls `GET /v1/models` and lists the Claude models. If the picker is empty, add exact Claude IDs from §3 in the Models section; the first entry is the default for new Code sessions. 5. Apply Changes, then Save & Restart. On the sign-in screen that appears after the relaunch, choose the option that starts the app with your inference-provider configuration (not the Anthropic sign-in), open the Code tab, pick a local folder and send a message. Gateway mode is local-only: no cloud sessions, SSH or Remote Control. Verify: the message gets an answer and the request shows in the cabinet under Usage. If the app shows the standard sign-in screen only, the configuration was not applied: quit completely (Cmd+Q on macOS, Task Manager on Windows) and reopen. `Gateway was unreachable` means the base URL or network is wrong (turn VPN/proxy off). `Error 403: Forbidden` means the app is on the Anthropic sign-in path. Diagnostics: Help → Troubleshooting → Generate Diagnostic Report → Export to file (`managed-config.txt` shows what was applied, `provider-status.txt` whether the provider settings are valid). Logs: `~/Library/Logs/Claude-3p/main.log` (macOS), `%LOCALAPPDATA%\Claude-3p\Logs\main.log` (Windows). ### 5.3 VS Code (Claude Code extension) The extension shares `~/.claude/settings.json` with the CLI: use the `env` block from §5.1, then fully restart VS Code. If the extension still shows a sign-in screen, set the same values in VS Code's own user settings (Command Palette → Preferences: Open User Settings (JSON)): ```json { "claudeCode.disableLoginPrompt": true, "claudeCode.environmentVariables": [ { "name": "ANTHROPIC_BASE_URL", "value": "https://api.oneprovider.dev" }, { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-your-key-here" } ] } ``` Verify: open the Claude Code panel (Command Palette → Claude Code: Focus), send `ping`, and expect an answer within seconds. ### 5.4 Codex (OpenAI CLI, Responses API) Codex talks to the `/v1/responses` surface. Export the key (`export ONEPROVIDER_API_KEY=sk-your-key-here`) in the shell that starts Codex, then in `~/.codex/config.toml` (desktop app: Settings → Configuration → Open config.toml): ```toml model_provider = "oneprovider" model = "gpt-6.1-sol" [model_providers.oneprovider] name = "OneProvider" base_url = "https://api.oneprovider.dev/v1" env_key = "ONEPROVIDER_API_KEY" wire_api = "responses" ``` `gpt-6.1-sol` is the current frontier GPT id. Set `model = "gpt-6.1-terra"` for the balanced tier or `model = "gpt-5.6-luna"` for the efficient tier. You can also use any Claude id from §3 on compatible endpoints. Restart Codex and start a new local task: existing tasks keep their provider. Verify with `codex` and a short read-only question; the request shows in the cabinet under Usage with `/v1/responses`. On macOS a desktop app started from the Dock may not see terminal variables; use Codex command-backed authentication instead of putting the key in `config.toml`. If Codex says "You've hit your usage limit" or asks to sign in with ChatGPT: that is the limit of a ChatGPT subscription, so the request went to ChatGPT and not to OneProvider, i.e. the provider is not active. Fix it in this order. (1) `model_provider = "oneprovider"` and `model = ...` must stand at the very top of `~/.codex/config.toml`, above any `[table]` header (a line under a header belongs to that table and is ignored). (2) Quit Codex completely and start a new local task: old tasks keep their old provider. (3) Sign out of ChatGPT (`codex logout`; in the desktop app, sign out in its settings) and start `codex` in the terminal where `ONEPROVIDER_API_KEY` is exported. With the provider active Codex works on the key alone and bills OneProvider, no ChatGPT login is needed; if it now asks to sign in or says the key is missing, the config is still not read (wrong file, the table above) or the variable is not visible to that process. Quick test without editing the file: `codex -c model_provider=oneprovider`. `wire_api` in Codex accepts only `"responses"`; Codex does not use `/v1/chat/completions`. ### 5.5 Cursor Cursor can override only the OpenAI base URL (not the Anthropic one), and only for GPT model IDs; Cursor's built-in Claude and Google models never use the override. It needs a Cursor plan that allows your own keys: Premium, Super or Ultra (or a legacy Pro, Pro+ or Ultra); Free and Plus ignore your own keys, and on Teams and Enterprise Cursor still adds its Token Rate to requests made with your own key. 1. Settings → Models → API Keys: paste the OneProvider key into **OpenAI API Key** and switch its toggle on (pasting alone does not enable it). 2. Turn on **Override OpenAI Base URL** and enter exactly `https://api.oneprovider.dev/v1` (with `/v1`, without `/chat/completions`). 3. Add a GPT model ID from §3 (a GPT text model ID, not an image model, for example `gpt-6.1-terra`) as a custom model and start a new Ask or Agent chat. Cursor applies the key and URL as you enter them (some versions also show a Save button). The override is global: while it is on, Cursor's own Composer and Grok models fail with `This model does not support custom API keys`; turn it off to use them again. Errors: `does not work with your current plan or api key` means the Free or Plus plan or the toggle is off; `Model name is not valid` means switch the toggle on and open a new chat; 404 or `Invalid URL` means the base URL is not exactly `https://api.oneprovider.dev/v1`. `The requested model is not available` or `Unauthorized User API key` right after the key was accepted: Cursor sent an id that is not in the catalog. When the id you added is also one of Cursor's own models, Cursor treats it as built-in and may append a reasoning suffix such as `-medium` to the id; Cursor staff call this a Cursor-side bug without a client-side fix, so check the id with a direct request, try another GPT id from §3, or use Cline. If Add does nothing or Cursor says the model is `already available as …`, the id is already in Cursor's own list: do not add it as a custom model; with the override on, pick Cursor's entry with that name in the model picker and Cursor sends the plain id. ### 5.6 Cline (VS Code extension) In Cline's API Provider settings choose **OpenAI Compatible**, set Base URL `https://api.oneprovider.dev/v1`, paste the key, and enter the exact model ID from §3 (for example `gpt-6.1-terra`). Claude IDs work in the same OpenAI Compatible provider. In the VS Code extension you can alternatively choose Provider `Anthropic`, tick “Use custom base URL” and enter `https://api.oneprovider.dev` (without `/v1`) with a Claude ID such as `claude-sonnet-5-5`; the Cline CLI has no base URL option for Anthropic. Verify with a small read-only task in a new Cline session. Image, tool-use and context features depend on the chosen model. Cline CLI: `npm i -g cline`, then `cline auth -p openai-compatible -k sk-your-key-here -m gpt-6.1-terra -b https://api.oneprovider.dev/v1`. ### 5.7 Hermes Agent (Nous Research) Run `hermes model` and choose "Custom endpoint (self-hosted / VLLM / etc.)", or set it in `~/.hermes/config.yaml` with `ONEPROVIDER_API_KEY=sk-your-key-here` in `~/.hermes/.env` (Hermes reads `OPENAI_BASE_URL` only for its `openai-api` provider): ```yaml model: default: gpt-6.1-terra provider: custom base_url: https://api.oneprovider.dev/v1 key_env: ONEPROVIDER_API_KEY ``` Keep the API mode on Chat Completions. Start a new Hermes session afterwards and ask a short question. Keep the key out of shell history and source control. ### 5.8 OpenCode Configure the provider in `~/.config/opencode/opencode.json` (or `opencode.jsonc`). OpenCode's `@ai-sdk/*` packages append only `/messages` (or `/responses`), so this base URL keeps `/v1`, unlike Claude Code's `ANTHROPIC_BASE_URL`: ```json { "provider": { "anthropic": { "npm": "@ai-sdk/anthropic", "options": { "baseURL": "https://api.oneprovider.dev/v1", "apiKey": "sk-your-key-here" } }, "openai": { "npm": "@ai-sdk/openai", "options": { "baseURL": "https://api.oneprovider.dev/v1", "apiKey": "sk-your-key-here" } } } } ``` Then run `/models` inside OpenCode (the command is `/models`, there is no `/model`; keybind `ctrl+x m`) and pick a model as `provider/model-id`. OpenCode lists only the models it already knows for a provider: to see another OneProvider model there (for example `kimi-k3`), add it under that provider's `models` block, as `"models": { "kimi-k3": { "name": "Kimi K3" } }`. The key can also be entered with the `/connect` command. Simpler ways: - Per project: put the same JSON in `opencode.json` in the project root. It applies only to that project and is merged over the global file. - Key not in the file: `/connect` inside OpenCode (or `opencode auth login` in a terminal) saves the key (in 1.x in `~/.local/share/opencode/auth.json`), so the config keeps only `baseURL`. Or write `"apiKey": "{env:ONEPROVIDER_KEY}"` and run `export ONEPROVIDER_KEY=sk-your-key-here`; the file then holds no secret and can be committed. An unset variable is replaced with an empty string. - Remote machine, CI or container, no copying of `~/.config` over SSH: keep `opencode.json` with `{env:ONEPROVIDER_KEY}` in the repository and set `ONEPROVIDER_KEY` on that machine (a CI secret, `docker run -e`, `export`). In OpenCode 1.x you can also give the whole config as one variable, `OPENCODE_CONFIG_CONTENT` (inline JSON, applied after all config files, nothing written to disk); `OPENCODE_CONFIG=/path/to/config.json` points to a config file elsewhere: ```bash export OPENCODE_CONFIG_CONTENT='{"provider":{"anthropic":{"npm":"@ai-sdk/anthropic","options":{"baseURL":"https://api.oneprovider.dev/v1","apiKey":"sk-your-key-here"}}}}' opencode ``` OpenCode 1.x or 2: run `opencode --version` (the number starts with 1 or 2). The config above is the 1.x format (`provider`, `npm`, `options`); OpenCode 2 reads it from the same places unchanged, so nothing needs to change. The native OpenCode 2 format is optional and writes the same settings with `providers`, `package` and `settings`, the AI SDK package getting an `aisdk:` prefix: ```json { "providers": { "anthropic": { "package": "aisdk:@ai-sdk/anthropic", "settings": { "baseURL": "https://api.oneprovider.dev/v1", "apiKey": "sk-your-key-here" } }, "openai": { "package": "aisdk:@ai-sdk/openai", "settings": { "baseURL": "https://api.oneprovider.dev/v1", "apiKey": "sk-your-key-here" } } } } ``` Do not point OpenCode 1.x at a file rewritten to the 2 format: both versions read the same files. `OPENCODE_CONFIG` and `OPENCODE_CONFIG_CONTENT` are documented for 1.x; on OpenCode 2 use `opencode.json` in the project and the `ONEPROVIDER_KEY` variable. ### 5.9 OpenClaw Config file: `~/.openclaw/openclaw.json` (create it if missing). `mode: "merge"` keeps OpenClaw's built-in providers next to OneProvider. Restart OpenClaw afterwards: ```json { "models": { "mode": "merge", "providers": { "oneprovider": { "baseUrl": "https://api.oneprovider.dev", "apiKey": "sk-your-key-here", "api": "anthropic-messages", "models": [ { "id": "claude-sonnet-5-5", "name": "OneProvider claude-sonnet-5-5", "api": "anthropic-messages", "input": ["text", "image"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 } } ] } } } } ``` Billing happens on OneProvider's side; the zero cost block only satisfies OpenClaw's UI. Add one entry per Claude ID from §3 you want to use. Full generated config with every model: `https://oneprovider.dev/docs/clients/openclaw`. ### 5.10 Open Cowork UI only, no config file. Gear icon (bottom-left) → API Settings → More Models: paste the key into API Key, set Protocol to `Anthropic`, set Base URL to `https://api.oneprovider.dev` (no `/v1`: the app appends `/v1/messages`), enter an exact Claude ID from §3 in Model, and Save. A model change takes effect on the next request without a restart. ### 5.11 Factory Droid Config file: `~/.factory/settings.json`. Add a bring-your-own-key model to `customModels`; keep `baseUrl` without `/v1` because the `anthropic` provider appends `/v1/messages`: ```json { "customModels": [ { "model": "claude-sonnet-5-5", "displayName": "OneProvider claude-sonnet-5-5", "baseUrl": "https://api.oneprovider.dev", "apiKey": "sk-your-key-here", "provider": "anthropic", "maxOutputTokens": 8192 } ] } ``` Run `/model` in droid and pick the entry under Custom models. droid also has an editor for these entries (`/settings` → Custom models, or `/model` → Manage custom models; the desktop app: Settings → Custom Models); there is no web UI, and personal custom models do not appear in Factory's web or mobile apps. A custom droid (`/droids`, files in `.factory/droids/`) uses the session model by default (`model: inherit`); to pin the OneProvider model for it, put `model: custom:claude-sonnet-5-5` in its frontmatter (`custom:` plus the entry's `model` field, not the display name). Droid's `/cost` is its own estimate; the charge is the per-request usage in the dashboard. ### 5.12 n8n (HTTP Request node) Create a Header Auth credential (Name `x-api-key`, Value the OneProvider key). In an HTTP Request node: Method `POST`, URL `https://api.oneprovider.dev/v1/messages`, Authentication Header Auth with that credential, headers `anthropic-version: 2023-06-01` and `content-type: application/json`, JSON body `{"model": "claude-sonnet-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "ping"}]}`. For the AI Agent node use the built-in chat models: an Anthropic credential with Base URL `https://api.oneprovider.dev` (no `/v1`, n8n adds it) for the Anthropic Chat Model, or an OpenAI credential with Base URL `https://api.oneprovider.dev/v1` for the OpenAI Chat Model (it uses the Responses API by default, which our API accepts for GPT and Claude IDs; switch Use Responses API off for Chat Completions). Add `"stream": true` and, under Options → Response, set Response Format to Text for streaming (the node returns the whole SSE text once the stream ends). Timeouts: without the Timeout option the HTTP Request node waits 5 minutes (300000 ms) for the response headers; once the option is added it starts at 10000 ms. Set Options → Timeout to 360000 or more for long non-streaming answers (our API may take up to 6 minutes to start answering); the OpenAI Chat Model node's Timeout is 60000 ms by default. ### 5.13 OpenAI-compatible clients (LibreChat, OpenWebUI, etc.) - API Base URL: `https://api.oneprovider.dev/v1` - API Key: your OneProvider key - Model name: any from §3 (use the canonical ID). TypingMind is not one of them: it wants the full endpoint, not a base URL (§5.15). Where the fields live: Open WebUI: Admin Settings → Connections → OpenAI API → add a connection (URL, key), then pick the model. LibreChat: a custom endpoint in `librechat.yaml` (`baseURL`, `apiKey`, `models`). SillyTavern: API → Chat Completion → source Custom (OpenAI-compatible) → Custom Endpoint (Base URL), key, model id. Roo Code shut down on 15 May 2026 (repository archived); its fork Kilo Code: Settings → Providers → Custom provider → OpenAI Compatible → Base URL, API key, models (it loads the list from `/v1/models`). GitHub Copilot Chat (BYOK): Command Palette → Chat: Manage Language Models → Add Models → Custom Endpoint; in `chatLanguageModels.json` set `"apiType": "chat-completions"`, the model `id` from §3, `url` `https://api.oneprovider.dev/v1/chat/completions`, `"toolCalling": true` (a model without tool calling is hidden) and `maxInputTokens`/`maxOutputTokens` from §3; in Copilot harness sessions also enable `chat.agentHost.byokModels.enabled`; chat and agent only, not inline suggestions. Continue (continue.dev): a model in `config.yaml` with `provider: openai`, `apiBase`, `apiKey`, `model`. ### 5.14 Responses API — curl ```bash curl -s https://api.oneprovider.dev/v1/responses \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "content-type: application/json" \ -d '{"model":"gpt-6.1-sol","input":"Say hi in one short sentence."}' ``` Swap `gpt-6.1-sol` for `gpt-6.1-terra` or `gpt-5.6-luna` to choose another current GPT tier. ### 5.15 TypingMind TypingMind takes no base URL: its custom model form wants the FULL endpoint address and appends nothing, so `https://api.oneprovider.dev/v1` alone (or the host without `/v1`) returns 404. Its built-in Claude (Anthropic) API key field talks to Anthropic directly and does not work with a OneProvider key; add a custom model instead. Guide: `https://oneprovider.dev/docs/clients/typingmind`. Models → Add custom model → Create Manually, then pick one API Type: - API Type `Claude Messages API`: Endpoint URL `https://api.oneprovider.dev/v1/messages`, Authentication Type API Key via HTTP Header, Header Key `x-api-key`, Header Value the OneProvider key. - API Type `OpenAI Chat Completions API`: Endpoint URL `https://api.oneprovider.dev/v1/chat/completions`, Header Key `Authorization`, Header Value `Bearer sk-...` (the word Bearer, a space, the key). - Model ID: the exact id from §3 (`claude-sonnet-5-5`, `gpt-6.1-terra`), not a display name such as "Claude Sonnet". One custom model per id. - Leave temperature at the default: Claude 5.x models do not need it, and a non-default temperature or top_p can make a request fail with 400 (reset it in the chat settings or switch it off under the model's Capabilities → Supported Parameters). - Route requests via TypingMind Cloud is not needed: the API allows browser requests (CORS). Then Test & Save and pick the model in a chat. ## 6. Streaming (SSE) Set `"stream": true`. Events are sent as soon as the model produces them, with no buffering. Any request, streaming included, is capped at 10 minutes. ```bash curl -N "$ANTHROPIC_BASE_URL/v1/messages" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 128, "stream": true, "messages": [{"role":"user","content":"count to 5 slowly"}] }' ``` Anthropic SSE event types: `message_start`, `content_block_start`, `content_block_delta`, `content_block_stop`, `message_delta`, `message_stop`. OpenAI route emits standard `data: {…}` chunks ending with `data: [DONE]`. For long generations, use streaming: a non-streaming request must start answering within 6 minutes, while a stream starts right away. Any request is capped at 10 minutes. ## 7. Tool use `tool_choice` is supported. Server-side normalization: - `tool_choice: "auto"` — passed through as-is. Default. - `tool_choice: {"type": "auto"}` — passed through. - `tool_choice: {"type": "any"}` — rewritten to `auto` + system hint instructing model to call a tool. - `tool_choice: {"type": "tool", "name": "X"}` — rewritten to `auto` + system hint asking for tool `X`. Not every model supports forced tool calls, so the API sends these two forms as `auto` plus a system hint. On `/v1/chat/completions`, forcing a call (`tool_choice` `required` or a named function) returns 400 on most Claude models: use `auto`, or `/v1/messages` with `any`. Your tool definitions, `input_schema`, and `tool_result` blocks are passed through untouched. ## 8. Error codes Every error is JSON of the same shape on every endpoint. The balance error also carries `code`; OpenAI SDKs read `error.message` as usual: ```json { "type": "error", "error": { "type": "insufficient_balance", "code": "insufficient_quota", "message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev" } } ``` | Status | error.type | Message | What to do | |--------|------------|---------|------------| | 400 | invalid_request_error | Varies; names what is malformed. | Fix the request. Do not resend it unchanged. | | 400 | invalid_request_error | `prompt is too long: N tokens > M maximum` (the model's own context limit; N and M vary per model) | Shorten the input or pick a larger-context model. Claude Code compacts automatically. | | 400 | invalid_request_error | `The requested model is not available` or `Model X is not available on this API key` (misspelled or outdated model ID, or the key's plan does not include it) | Pick a model listed by `GET /v1/models` or on the pricing page. | | 400 | invalid_request_error | `The request was blocked by the content policy; change it and retry` (mostly images and video) | Change the prompt or the input files; the same request gets the same answer. | | 401 | authentication_error | `Invalid API key`, `API key is required` | Send the raw `sk-…` key in `x-api-key` or `Authorization: Bearer`, without quotes. | | 401 | authentication_error | `API key is disabled` (key disabled or account inactive) | Check the key in the cabinet (Keys page) or contact `@Oneproviderhelpbot`. | | 403 | permission_error | `API key expired` | Extend the key or issue a new one in the cabinet (Keys page). | | 404 | invalid_request_error | `The requested API endpoint does not exist` (usually a wrong base URL, for example `/v1` repeated twice in the path) | Claude Code / Anthropic SDKs: `https://api.oneprovider.dev`; OpenAI SDKs: `https://api.oneprovider.dev/v1`. | | 413 | invalid_request_error | `request body exceeds size limit` (32 MB) | Send smaller or fewer files, or split the request. | | 429 | insufficient_balance | `Insufficient balance on this API key. Top up: dashboard.oneprovider.dev`; `error.code` is `insufficient_quota`, header `x-should-retry: false` | Do not retry. Top up the cabinet or raise the key's spend limit, then resend. | | 429 | rate_limit_error | `Rate limit exceeded; retry later`; may carry `Retry-After` | Wait `Retry-After` seconds if present, otherwise back off and retry. | | 500, 502 | server_error | `Service temporarily unavailable; retry later` | Retry with backoff. | | 503 | server_error | `Service temporarily unavailable; retry later` | Transient; retry with backoff. Nothing is wrong with the key. | | 504 | server_error | `Service timed out; retry later` | Retry; use streaming for long generations. | Time limits: a non-streaming request must start answering within 6 minutes; any request, streaming included, is capped at 10 minutes. Errors inside a stream: the Messages API sends an `event: error` frame with the same error body; the Responses API sends `response.failed` with the reason in `response.error`. ## 9. Retry strategy - Do not retry 400, 401, 403, 404, 413, or `429 insufficient_balance`; fix the request, key, or balance first. Respect `x-should-retry: false` (the official Anthropic and OpenAI SDKs already do). - Retry `429 rate_limit_error`, `500`, `502`, `503`, `504` with exponential backoff and jitter (1s, 2s, 4s, up to a minute). Honor `Retry-After` when present. - For long generations, use streaming. ## 10. Usage and billing - Pay-as-you-go in USD. Keys are valid for 1 to 90 days depending on the key; user balance does not expire. - Top up in the cabinet (bot: Account → Top up Account; site: Balance → Top up) with crypto, cards from any country with Apple Pay / Google Pay, or SBP/QR. A single cabinet top-up is $100 to $5000; larger top-ups get a better price per $1 of balance. Credit clears in 1–3 minutes typical, ≤3 hours worst case. - Fees: SBP/QR charges the customer 3.5% while OneProvider subsidizes another 3.5%; crypto has a 3% provider fee plus the customer-paid network fee. - Refund policy: https://oneprovider.dev/legal/refund. - Get an API key, top up, and check balance in your personal cabinet (`@oneprovider_robot` on Telegram or `https://app.oneprovider.dev`) or programmatically via `GET /v1/dashboard/balance` (see §10.1). ## 10.1 Balance endpoints `GET /v1/dashboard/balance` on `https://api.oneprovider.dev` returns your key's current balance. **Authentication:** `Authorization: Bearer sk-...` header (`x-api-key` is accepted here too). **Request:** ```bash curl -H "Authorization: Bearer sk-your-key-here" \ https://api.oneprovider.dev/v1/dashboard/balance ``` **Response (200 OK):** ```json { "object": "balance", "balance_usd": 54.77, "expires_at": "2026-07-29T19:00:00Z", "is_active": true, "last_synced_at": "2026-06-29T19:52:00Z" } ``` - `balance_usd`: the key's available balance in USD - `expires_at`: key expiry (ISO 8601 UTC, `null` if none) - `is_active`: false if the key is paused or disabled - `last_synced_at`: when the balance was last updated **OpenAI-compatible balance paths** (for apps such as NextChat and LobeChat, same Bearer key): - `GET /v1/dashboard/billing/subscription`: `hard_limit_usd` is the remaining balance - `GET /v1/dashboard/billing/usage`: `total_usage` is always 0 (in cents) - `GET /v1/dashboard/billing/credit_grants`: `total_available` is the remaining balance **Errors:** - `401`: missing or invalid `Authorization: Bearer` header - `429`: rate limit exceeded; balance endpoints are rate-limited per IP ## 11. Operational facts - Region: EU (Frankfurt). - TLS 1.3, HTTP/2. ALPN negotiated. - Latency (Sonnet, 1 output token, end-to-end): p50 ≈ 2.4s, p90 ≈ 3.6s. - Non-streaming requests must start answering within 6 minutes; any request is capped at 10 minutes. - VPN/VLESS proxies often break SSE and HTTP/2 ALPN — disable them if you see truncated outputs. - No geoblocking. ## 12. Migrating from `api.anthropic.com` or `api.openai.com` Change exactly two things: the base URL and the API key. Schema is identical. | From | To | Variable changed | |-------------------------|------------------------------------------|--------------------------| | `api.anthropic.com` | `api.oneprovider.dev` | `ANTHROPIC_BASE_URL` | | `api.openai.com/v1` | `api.oneprovider.dev/v1` | `OPENAI_BASE_URL` | Existing request/response code does not change. OpenAI clients keep using `openai.ChatCompletion` (or `chat.completions`); the API handles the format server-side. ## 13. Free web search Claude models search the web themselves: Claude Code's `WebSearch` tool and the Messages API tool `web_search_20250305` (or `web_search_20260209`, `"tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}]`) work through a OneProvider key; each search is counted in `usage.server_tool_use.web_search_requests`. GPT models on `/v1/responses` accept the `web_search` tool but do not search (they answer from memory). For GPT models and for clients without a search tool of their own, use Tavily separately without changing the OneProvider key. - Free tier: 1,000 API credits every month, no card required. - API key: `https://app.tavily.com/` - Python: `pip install tavily-python`, then pass `TAVILY_API_KEY` to `TavilyClient`. - Claude Code: `claude mcp add tavily --transport http https://mcp.tavily.com/mcp/`, then complete OAuth in the browser. - Full guide: `https://oneprovider.dev/docs/guides/web-search` ## 14. Sources of truth - This bundle: `https://oneprovider.dev/docs/llms.txt` - Short discovery index: `https://oneprovider.dev/llms.txt` - Human docs (rendered): `https://oneprovider.dev/docs` - Cabinet and keys guide: `https://oneprovider.dev/docs/first-key` - Personal cabinet (keys, balance, usage): `https://app.oneprovider.dev` - Sitemap: `https://oneprovider.dev/sitemap.xml` - Support: `https://t.me/Oneproviderhelpbot` If anything in this file conflicts with the live API behavior, the live API wins; report the drift to support.