Available models
—
API Documentation & Technical Reference
SubPool provides a high-performance Universal AI Gateway fully compatible with OpenAI Chat Completions and Anthropic Messages protocols. Connect via official SDKs, cURL, or integrate seamlessly into your backend services.
Quickstart & Authentication
SubPool is a high-performance universal AI gateway. Use one API key to access 50+ leading models from OpenAI, Anthropic, Google Gemini, DeepSeek, and other providers through industry-standard APIs.
1 Core connection settings
| Parameter | Configuration value | Applies to |
|---|---|---|
| Base URL (OpenAI) | https://subpool.net/v1 |
OpenAI SDK, Cursor, Cline, OpenCode, Continue, Python & Node.js |
| Base URL (Anthropic) | https://subpool.net |
Claude Code CLI, Claude Desktop App, @anthropic-ai/sdk |
| API Key | sk-xxxxxxxxxxxxxxxx Create a key at Manage API keys | All requests to the SubPool Gateway |
| Model ID | claude-3-7-sonnet, gpt-4o, deepseek-chat... Find the exact model ID on the Pricing & Models | Automatically routed by model ID |
2 Request authentication headers
SubPool accepts both common authentication header formats. Choose the one supported by your tool or library:
OpenAI format (Authorization Bearer)
HTTP Header
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
For the OpenAI Python/Node SDKs, cURL, LangChain, LlamaIndex, and Cursor.
Anthropic format (x-api-key)
HTTP Header
x-api-key: sk-xxxxxxxxxxxxxxxx anthropic-version: 2023-06-01
For the Anthropic SDK, Claude Code CLI, and Claude Desktop.
3 Send your first connection test request
Run a simple cURL command in your terminal to verify the connection and API key:
bash / zsh cURL
curl https://subpool.net/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SUBPOOL_API_KEY" \
-d '{
"model": "claude-3-7-sonnet",
"messages": [
{"role": "system", "content": "You are a helpful AI expert."},
{"role": "user", "content": "Hello! Please confirm the connection to the SubPool Gateway."}
],
"temperature": 0.7
}'
Sample success response (HTTP 200 OK)
application/json
{
"id": "chatcmpl-8zV3A4kL9Qx8p",
"object": "chat.completion",
"created": 1729061000,
"model": "claude-3-7-sonnet",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Connection successful! The SubPool Gateway is ready to process your request."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 18,
"total_tokens": 46
}
}
Integrating an IDE or AI coding agent?
We provide detailed setup guides for Claude Code CLI, Cursor, Cline, Continue, OpenCode, and Codex CLI, including OS-specific instructions and one-click setup scripts.
OpenAI Chat Completions
The API follows the OpenAI API format and supports text generation, SSE streaming, tool/function calling, and vision.
SDK integration examples
cURL CLI
curl https://subpool.net/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SUBPOOL_API_KEY" \
-d '{
"model": "claude-3-7-sonnet",
"messages": [
{"role": "system", "content": "You are a professional software architect."},
{"role": "user", "content": "Explain idempotent APIs with a clear example."}
],
"temperature": 0.7,
"max_tokens": 1500,
"stream": false
}'
Python 3 · pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("SUBPOOL_API_KEY"),
base_url="https://subpool.net/v1",
)
response = client.chat.completions.create(
model="claude-3-7-sonnet",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Write a quicksort implementation in Python."},
],
temperature=0.7,
stream=False,
)
print(response.choices[0].message.content)
Node.js · npm install openai
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.SUBPOOL_API_KEY,
baseURL: "https://subpool.net/v1",
});
const completion = await client.chat.completions.create({
model: "claude-3-7-sonnet",
messages: [
{ role: "system", content: "You are a TypeScript expert." },
{ role: "user", content: "Define a generic Result type." },
],
stream: false,
});
console.log(completion.choices[0].message.content);
Request body parameters
| Field | Type | Description |
|---|---|---|
| model | string (required) | The target model ID (for example, claude-sonnet-5-5, gpt-6.1-sol, or deepseek-chat). |
| messages | array (required) | Messages using the role structure (`system`, `user`, `assistant`, `tool`) and content. |
| stream | boolean (optional) | When `true`, the server streams Server-Sent Events (SSE) token by token. Defaults to `false`. |
| temperature | number (optional) | Controls randomness, from 0.0 (more deterministic) to 2.0 (more creative). For coding, 0.2–0.7 is recommended. |
| max_tokens | integer (optional) | Maximum number of tokens to generate in the response. |
| tools | array (optional) | List of function definitions for OpenAI-compatible tool calling. |
SSE streaming & reasoning models
For reasoning models such as DeepSeek R1 or Claude Sonnet with extended thinking, reasoning may be returned in the reasoning_content or in a separate reasoning block:
Server-Sent Events (SSE Stream)
data: {"choices":[{"delta":{"reasoning_content":"First, let us analyze the base case..."}}]}
data: {"choices":[{"delta":{"content":"Here is the detailed solution..."}}]}
data: [DONE]
Anthropic Messages API
For Claude Code CLI, Claude Desktop, and applications using the official Anthropic SDK. Supports extended thinking and prompt caching.
Anthropic SDK integration example
cURL CLI
curl https://subpool.net/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $SUBPOOL_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-3-7-sonnet",
"max_tokens": 1500,
"system": "You are a senior software engineer.",
"messages": [
{"role": "user", "content": "Optimize the following SQL query for the fastest possible execution..."}
]
}'
Python 3 · pip install anthropic
import os
import anthropic
client = anthropic.Anthropic(
api_key=os.environ.get("SUBPOOL_API_KEY"),
base_url="https://subpool.net",
)
message = client.messages.create(
model="claude-3-7-sonnet",
max_tokens=2048,
system="You are a professional programming assistant.",
messages=[
{"role": "user", "content": "Design an event-driven microservices architecture."}
],
)
print(message.content[0].text)
Node.js · npm install @anthropic-ai/sdk
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: process.env.SUBPOOL_API_KEY,
baseURL: "https://subpool.net",
});
const message = await client.messages.create({
model: "claude-3-7-sonnet",
max_tokens: 1500,
messages: [{ role: "user", content: "Hello from the Claude SDK!" }],
});
console.log(message.content[0].text);
Anthropic parameters & extended thinking
- Separate system prompt: Anthropic passes the system prompt as a top-level parameter
system: "...", rather than inside themessages. - Required `max_tokens` field: Every Messages API request must specify
max_tokens(for example: 1024, 2048, or 4096). - Enable Extended Thinking (Claude): Add
"thinking": {"type": "enabled", "budget_tokens": 4096}to the request body to enable deeper reasoning.
Computer vision & multimodal input
Analyze images, read documents with OCR, review UI/UX designs, and debug screenshots with leading vision models (GPT-6, Claude, Gemini).
POST /v1/chat/completions
POST /v1/messages
1 Overview & use cases
SubPool Gateway accepts images directly in chat requests. You can provide a public URL or Base64-encoded string (data:image/jpeg;base64,...).
OCR & document reading
Extract tables, invoices, handwriting, and legal documents with high accuracy.
UI/UX & Frontend Code
Turn screenshots or Figma mockups into complete HTML/Tailwind/React code.
Chart analysis & debugging
Interpret financial charts, system architecture, and error logs captured from a terminal.
2 OpenAI vision format (cURL, Python & Base64)
In the OpenAI format, a message’s content is an array containing both text and image blocks:
cURL · Send an image URL
curl https://subpool.net/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SUBPOOL_API_KEY" \
-d '{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "Analyze the system architecture in this diagram and identify potential bottlenecks:"},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/system-architecture.png",
"detail": "high"
}
}
]
}
],
"max_tokens": 1000
}'
Python 3 · Read a local image file and encode it as Base64
import os
import base64
from openai import OpenAI
def encode_image(image_path):
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode("utf-8")
client = OpenAI(
api_key=os.environ.get("SUBPOOL_API_KEY"),
base_url="https://subpool.net/v1",
)
base64_image = encode_image("screenshot-error.png")
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Read the error message in this screenshot and explain how to fix it:"},
{
"type": "image_url",
"image_url": {
"url": f"data:image/png;base64,{base64_image}"
},
},
],
}
],
max_tokens=800,
)
print(response.choices[0].message.content)
Node.js · fs & OpenAI SDK
import fs from "fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.SUBPOOL_API_KEY,
baseURL: "https://subpool.net/v1",
});
const imageBase64 = fs.readFileSync("receipt.jpg").toString("base64");
const response = await client.chat.completions.create({
model: "gpt-4o",
messages: [
{
role: "user",
content: [
{ type: "text", text: "Extract the item list and total amount from this invoice as JSON:" },
{
type: "image_url",
image_url: {
url: `data:image/jpeg;base64,${imageBase64}`,
},
},
],
},
],
});
console.log(response.choices[0].message.content);
3 Anthropic vision format (POST /v1/messages)
For Claude models, you can send images using Anthropic’s native source object format:
cURL Anthropic Vision Payload
curl https://subpool.net/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $SUBPOOL_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-3-7-sonnet",
"max_tokens": 1500,
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
}
},
{
"type": "text",
"text": "Describe this image and explain its key details."
}
]
}
]
}'
4 Supported formats & token cost optimization
- Supported file formats: PNG (
image/png), JPEG (image/jpeg), WEBP (image/webp) and GIF (image/gif). - Recommended size: Up to 20 MB per image. For high-resolution images (>2048 px), compress or resize them slightly to improve transfer speed.
- Detail parameter (OpenAI): Use
detail: "low"for quick image classification tasks that use only 85 fixed tokens. Usedetail: "high"when you need to inspect small text or complex diagrams.
Error codes & troubleshooting
SubPool returns standard HTTP status codes with detailed JSON error bodies to help developers debug and handle failures programmatically.
1 Standard error response JSON
Error Response JSON
{
"error": {
"message": "Insufficient account balance to process this request. Please add funds.",
"type": "insufficient_quota",
"param": null,
"code": "balance_exhausted"
}
}
2 HTTP status codes
| HTTP status | Error | Cause & solution |
|---|---|---|
| 400 | Bad Request | Invalid JSON syntax or missing a required field (for example, model or messages). |
| 401 | Unauthorized | API key is invalid, disabled, or has an invalid Bearer header. Check the key on the API Keys page. |
| 402 | Payment Required | Your account balance is empty or too low for the estimated minimum charge. Add funds on the Top Up page. |
| 404 | Not Found | The model ID does not exist or is temporarily unavailable. Check the exact model ID on the pricing page. |
| 429 | Too Many Requests | Request rate limit exceeded (RPM/TPM). Use a retry strategy with exponential backoff. |
| 500 / 502 | Upstream Error | The upstream model provider returned an error. The system will retry through a backup route when available. |
3 Production error-handling recommendations
Exponential Backoff & Jitter
For 429 or 503 errors, do not retry immediately. Increase the wait time between attempts (for example, 1s, 2s, 4s, and 8s with jitter) to avoid overloading the service.
Automatic balance monitoring
Handle 402 errors by notifying Slack/Telegram or setting a low-balance alert on the dashboard so your app is not interrupted.
Models
Model overview
Compare supported models, capabilities, and specifications, then choose the right model for your workload.
Providers
—
Capability types
—
Models by provider
See the active catalog grouped by provider, with higher-priority models first.
Loading model catalog…
Capability coverage
Available models that support each capability.
→
Catalog
Browse available models by provider, capabilities, and context size.
→
Pricing
Transparent token-based pricing, supported capabilities (Thinking, Vision, Tools, Img2img), and specifications for 50+ frontier AI models.
Models
Model catalog
Browse available models by provider, capabilities, and context size.
| Model | Provider | Capabilities | Context window | Max output | |
|---|---|---|---|---|---|
| Loading model catalog… | |||||
AI model pricing
Transparent token-based pricing, supported capabilities (Thinking, Vision, Tools, Img2img), and specifications for 50+ frontier AI models.
All prices are in USD per 1M tokens.
Filters:
| Model | Provider | Input | Output | Cache write | Cache read |
|---|
Model ID
Price
/ 1M tokensPrice
Output
Cache write
Cache read
Minimum per request
Developer Tools & AI Coding Agent Guides
Detailed guides to help you connect and use AI tools (Claude Code, Cursor, Codex CLI, OpenCode...) directly with our high-performance Gateway at undefined.
Before you start — 3 things you need ready
1. API Key
Create at Manage API Keys, format sk-xxxxxxxx. Shows only once — save immediately.
2. Base URL
Use exact /v1. Use the URL shown in each tool's example. SubPool also tolerates a duplicated /v1 prefix, but omitting it is recommended when the tool appends /v1 itself.
3. Model ID
Get exact ID (e.g. claude-sonnet-4-6) at Pricing page — click copy icon next to any model.
Select a tool to view detailed guide
12 supported tools
Claude Code
Terminal coding agent, Anthropic standard
View guide
→
Claude (Desktop app)
Claude desktop app, configured via inference gateway
View guide
→
Codex CLI
OpenAI coding agent, Responses API standard
View guide
→
ChatGPT (Desktop app)
The Codex tab built into OpenAI's official ChatGPT Desktop App
View guide
→
OpenCode CLI
Open-source multi-provider terminal coding agent
View guide
→
Cursor IDE
AI-native IDE based on VS Code
View guide
→
Cline
VS Code extension coding agent
View guide
→
Continue
Autocomplete & chat extension for VS Code / JetBrains
View guide
→
DeepSeek CLI
TOML configured CLI, OpenAI standard
View guide
→
Back to all tools
SubPool Integrations
Claude Code
Terminal coding agent, Anthropic standard
Stable (Multilingual)
Endpoint: /v1/messages
1
Requirement
This configuration works for both Claude Code CLI and Claude Code in Visual Studio Code. Install either the CLI (npm install -g @anthropic-ai/claude-code) or the Claude Code extension from the Visual Studio Code Marketplace. Node.js >= 18 is required either way.
Claude Code CLI
npm install -g @anthropic-ai/claude-code
2
Choose your OS
3
Choose how to set up
Fastest way
about 1 minute
Step 1 — Open Terminal: press Cmd + Space, type Terminal, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
Terminal (macOS)
curl -fsSL /setup/claude-code/claude-code.sh | bash
Step 1 — Open PowerShell: press the Windows key, type powershell, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
PowerShell (Windows)
irm /setup/claude-code/claude-code.ps1 | iex
The script asks for your SubPool API key, then lets you pick a model for each of the 4 roles Claude Code uses — FABLE, OPUS, SONNET, HAIKU (press Enter on any of them to use Model Switch, so you can change the model later from the website without rerunning the script). If a settings.json already exists, it is renamed to settings_backup_<timestamp>.json right next to it before the new one is written — nothing is ever deleted.
Claude Code reads ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN from the settings JSON file — writing them directly to settings.json is more reliable than exporting them temporarily in a shell. Use the URL exactly as shown below, ending in /v1.
- Open Terminal, create directory if needed: mkdir -p ~/.claude
- Edit ~/.claude/settings.json and paste configuration below.
- Save file, restart terminal, run claude to start.
~/.claude/settings.json
{
"hasCompletedOnboarding": true,
"env": {
"ANTHROPIC_BASE_URL": "/v1",
"ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx",
"ANTHROPIC_DEFAULT_FABLE_MODEL": "gpt-5-6-sol",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5-6-terra",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5-6-terra",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5-6-luna"
}
}
- Open PowerShell, create directory: mkdir $env:USERPROFILE\.claude
- Edit %USERPROFILE%\.claude\settings.json and paste configuration below.
- Save file, restart PowerShell/WSL, run claude.
%USERPROFILE%\.claude\settings.json
{
"hasCompletedOnboarding": true,
"env": {
"ANTHROPIC_BASE_URL": "/v1",
"ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx",
"ANTHROPIC_DEFAULT_FABLE_MODEL": "gpt-5-6-sol",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5-6-terra",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5-6-terra",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5-6-luna"
}
}
Note
Claude Code only reads settings.json on startup — open a new session after editing. SubPool also tolerates a duplicated /v1 prefix if you accidentally add one, but the URL shown above (ending in /v1) is the recommended configuration.
Verify Connection
Run claude in any folder and send a prompt. Response without 401 error confirms setup.
Back to all tools
SubPool Integrations
Claude (Desktop app)
Claude desktop app, configured via inference gateway
Endpoint: /v1/chat/completions
1
Prerequisites
- Claude Desktop installed (macOS or Windows) — see Step 2 below to enable Developer Mode, a required step before anything else here.
- Quit the app completely before editing the file. As with Cline, edits made while the app is running get overwritten when it saves its own state.
- Only the macOS path is verified. The Windows path is inferred from where the app conventionally stores its config — if your machine has no such folder, use the lookup command in the Windows tab below.
2
Choose your OS
3
Connect the Gateway for the first time
On macOS there's nothing elaborate to do: on the app's opening screen (Get Started), just click Or sign in with Gateway.
This step is required on Windows for both paths in Step 3 below. A normal claude.ai sign-in does NOT create this config — it's a separate, hidden feature.
- Open Claude App (the sign-in / Get Started screen).
- Click the ☰ menu top-left → Help → Troubleshooting → Enable Developer Mode.
- The ☰ menu now shows a Developer item → click Developer → Configure Third-Party Inference…. On the Connect tab, set Credential kind to Static API Key.
- Enter
undefinedfor Gateway base URL, and enter any temporary value for API Key (it will be overwritten in Step 3 below), then click Apply Changes. - A restart confirmation popup appears — click Restart right away to apply it.
4
Choose how to set up
Fastest way
about 1 minute
Paste the single line below into a command window and press Enter. The script asks for your API key and model, then writes the config for you. You never have to find a hidden folder or edit JSON, and any existing file is backed up before it is replaced.
The script lists the Claude models active on your account for you to pick from (Model Switch and other providers' models don't work here).
Step 1 — Open Terminal: press Cmd + Space, type Terminal, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
Terminal (macOS)
curl -fsSL /setup/claude-app/claude-app.sh | bash
Step 1 — Open PowerShell: press the Windows key, type powershell, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
PowerShell (Windows)
irm /setup/claude-app/claude-app.ps1 | iex
Note
Three things differ from the other tools here: (1) inferenceGatewayBaseUrl must be the bare domain, with NO trailing /v1 — the app appends /v1/messages and /v1/models itself, so adding /v1 makes it call /v1/v1/... and show "organization's model list hasn't loaded". (2) Every entry in inferenceModels[] must be a real Anthropic model id (like the models in the example below) — the Model Switch alias (switch-default) doesn't work here, showing "not an Anthropic model". (3) Add inferenceGatewayAuthScheme: "bearer" and modelDiscoveryEnabled: true as shown. Get the exact id of an active model on the pricing page.
- Quit Claude entirely with Cmd + Q — closing the window is not enough.
- Open the config folder: in Finder press Cmd + Shift + G, paste
~/Library/Application Support/Claude-3p/configLibrary/and hit Enter. Find the<appliedId>.jsonfile for the profile you use — with a single profile there is exactly one.jsonin there. - Set or add the keys exactly as shown below. Replace
sk-xxx...with your real API key. - Save the file (Ctrl + S, or Cmd + S on macOS) and reopen Claude.
~/Library/Application Support/Claude-3p/configLibrary/<appliedId>.json
{
"inferenceProvider": "gateway",
"inferenceGatewayBaseUrl": "",
"inferenceGatewayApiKey": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx",
"inferenceGatewayAuthScheme": "bearer",
"modelDiscoveryEnabled": true,
"inferenceModels": [
{ "name": "claude-fable-5" },
{ "name": "claude-opus-5" },
{ "name": "claude-sonnet-5" },
{ "name": "claude-haiku-4-5-20251001" }
]
}
- Quit Claude entirely. Clicking the X is not enough — the app keeps running in the background. Look at the system tray (bottom-right of the screen, next to the clock; you may need to click the ^ arrow to see all icons), right-click the Claude icon and choose Quit (or Exit).
- Double-check it is closed. Press Ctrl + Shift + Esc to open Task Manager. On the Processes tab, if any entry named Claude is still listed, right-click it and choose End task.
- Open the config folder. Press Windows + R, type
%APPDATA%and press Enter — Explorer opens atC:\Users\<your-name>\AppData\Roaming. Look for a folder whose name starts with "Claude" (e.g.Claude-3p), open it, then go into the configLibrary subfolder.
Can't find the folder?
If Explorer says "Location is not available", or you see no Claude folder at all, open PowerShell (press Windows, type PowerShell, Enter) and paste the command below. It prints the exact path on your machine:
PowerShell
Get-ChildItem "$env:APPDATA","$env:LOCALAPPDATA" -Recurse -Directory -Filter configLibrary -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName
If the command prints nothing, the folder was never created — go back to Step 2 above and complete all 5 Enable Developer Mode steps, then run the command again. This is not about forgetting to sign in.
- Open the right file in the right editor. The folder holds one or more
<appliedId>.jsonfiles; if there are several, pick the one with the most recent Date modified. Right-click → Open with → Visual Studio Code (or Notepad++). Do not use Word or WordPad — they corrupt the file format. - Set or add the keys exactly as shown below. Replace
sk-xxx...with your real API key. - Save the file (Ctrl + S, or Cmd + S on macOS) and reopen Claude.
configLibrary\<appliedId>.json
{
"inferenceProvider": "gateway",
"inferenceGatewayBaseUrl": "",
"inferenceGatewayApiKey": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx",
"inferenceGatewayAuthScheme": "bearer",
"modelDiscoveryEnabled": true,
"inferenceModels": [
{ "name": "claude-fable-5" },
{ "name": "claude-opus-5" },
{ "name": "claude-sonnet-5" },
{ "name": "claude-haiku-4-5-20251001" }
]
}
Note
If configLibrary holds several .json files (several profiles), editing the wrong one has no effect. The reliable way: open _meta.json in the same folder — its appliedId field names the active profile's .json file. No _meta.json? Check each file's last modified time, or open the app first to see which profile is active before quitting to edit.
Verify Connection
Reopen Claude. If it shows a sign-in screen, choose Continue with Gateway (do not sign in with a claude.ai account). If that screen shows “Your provider setup needs a fix”, your inferenceModels field is still wrong — see the note above. Once past that screen, start a new session and send a short prompt to confirm the gateway points at SubPool.
Back to all tools
SubPool Integrations
Codex CLI
OpenAI coding agent, Responses API standard
Endpoint: /v1/responses
1
Prerequisites
- Codex CLI installed via npm, or the Codex extension from the VS Code Marketplace — both share the config below.
- Configured via TOML format — [model_providers.subpool] header is case sensitive.
- If this machine has previously installed Codex and done `codex login` with a ChatGPT account, log out first: open a terminal and run codex logout.
2
Choose your OS
3
Choose how to set up
Fastest way
about 1 minute
Paste the single line below into a command window and press Enter. The script asks for your API key and model, then writes the config for you. You never have to find a hidden folder or edit JSON, and any existing file is backed up before it is replaced.
Step 1 — Open Terminal: press Cmd + Space, type Terminal, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
Terminal (macOS)
curl -fsSL /setup/codex/codex.sh | bash
Step 1 — Open PowerShell: press the Windows key, type powershell, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
PowerShell (Windows)
irm /setup/codex/codex.ps1 | iex
Step 1 — create/edit ~/.codex/auth.json:
~/.codex/auth.json
{
"auth_mode": "apikey",
"OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"
}
Step 2 — create/edit ~/.codex/config.toml. The name field is required — Codex errors on startup without it. env_key and requires_openai_auth = false are also required — without them, a machine that has ever done `codex login` with a ChatGPT account gets a 401 missing API key error even with the right key:
~/.codex/config.toml
model = "switch-default" model_provider = "subpool" [model_providers.subpool] name = "SubPool" base_url = "/v1" wire_api = "responses" env_key = "SUBPOOL_API_KEY" requires_openai_auth = false
Step 3 — set the SUBPOOL_API_KEY environment variable (Codex reads the key via env_key from step 2, not directly from auth.json, for a custom provider):
Terminal (macOS)
echo 'export SUBPOOL_API_KEY="sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"' >> ~/.zshrc launchctl setenv SUBPOOL_API_KEY "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"
Step 4 — open a new Terminal window (to pick up the env var you just set), then restart Codex CLI completely.
Step 1 — create/edit %USERPROFILE%\.codex\auth.json:
%USERPROFILE%\.codex\auth.json
{
"auth_mode": "apikey",
"OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"
}
Step 2 — create/edit %USERPROFILE%\.codex\config.toml. env_key and requires_openai_auth = false are required — without them, a machine that has ever done `codex login` with a ChatGPT account gets a 401 missing API key error even with the right key:
%USERPROFILE%\.codex\config.toml
model = "switch-default" model_provider = "subpool" [model_providers.subpool] name = "SubPool" base_url = "/v1" wire_api = "responses" env_key = "SUBPOOL_API_KEY" requires_openai_auth = false
Step 3 — set the SUBPOOL_API_KEY environment variable (run in PowerShell, no admin rights needed):
PowerShell
[Environment]::SetEnvironmentVariable('SUBPOOL_API_KEY', 'sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx', 'User')
Step 4 — open a new PowerShell window, then restart Codex CLI completely.
401 missing API key even with the right key
If this machine has ever done `codex login` with a ChatGPT account, Codex prefers that login state and won't attach Authorization to requests for a custom provider based on auth.json alone — even with the correct key entered. The surest fix is to log out before configuring: run codex logout. The Quick install script above already prompts for this and handles the config side (sets env_key plus the environment variable); doing it manually, make sure you have both the env_key/requires_openai_auth lines in config.toml AND the environment variable step above — missing either one still causes the error.
Codex CLI Specific Error
Error 'provider name must not be empty' means name = "SubPool" is missing under [model_providers.subpool].
Check the model after opening Codex
After configuring and opening Codex, if the model shown is Custom, that's correct — use it as-is. Do NOT switch to a different model from Codex's built-in list — switching makes Codex fall back to OpenAI's default provider (no longer going through SubPool), which won't work.
Verify Connection
Open Codex, start a new chat session, and send a short message. A normal reply (no 401 or invalid api key error) confirms it's talking to SubPool.
Back to all tools
SubPool Integrations
ChatGPT (Desktop app)
The Codex tab built into OpenAI's official ChatGPT Desktop App
Stable (Multilingual)
Endpoint: /v1/responses
1
Prerequisites
- ChatGPT (Desktop App) installed, with the Codex tab open in the app.
- ChatGPT Desktop App reads the same ~/.codex/config.toml and auth.json as Codex CLI/the VS Code extension (confirmed in OpenAI's official docs) — there's no separate config file for it.
- If this machine has previously signed in to a ChatGPT account in Codex/ChatGPT App, sign out first: run codex logout in a terminal if Codex CLI is installed, or sign out directly in the app (account/profile menu) if you have no terminal.
Note
Quit ChatGPT (Desktop App) completely before running the script — if it's still running, it can overwrite what you just wrote when you later quit it.
2
Choose your OS
3
Choose how to set up
Fastest way
about 1 minute
Paste the single line below into a command window and press Enter. The script asks for your API key and model, then writes the config for you. You never have to find a hidden folder or edit JSON, and any existing file is backed up before it is replaced.
Step 1 — Open Terminal: press Cmd + Space, type Terminal, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
Terminal (macOS)
curl -fsSL /setup/chatgpt-app/chatgpt-app.sh | bash
Step 1 — Open PowerShell: press the Windows key, type powershell, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
PowerShell (Windows)
irm /setup/chatgpt-app/chatgpt-app.ps1 | iex
Step 1 — create/edit ~/.codex/auth.json:
~/.codex/auth.json
{
"auth_mode": "apikey",
"OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"
}
Step 2 — create/edit ~/.codex/config.toml (name field is required). env_key and requires_openai_auth = false are also required — without them, a machine that has ever done `codex login` with a ChatGPT account gets a 401 missing API key error even with the right key:
~/.codex/config.toml
model = "switch-default" model_provider = "subpool" [model_providers.subpool] name = "SubPool" base_url = "/v1" wire_api = "responses" env_key = "SUBPOOL_API_KEY" requires_openai_auth = false
Step 3 — set the SUBPOOL_API_KEY environment variable for GUI apps (the app reads the key via env_key from step 2, not directly from auth.json, for a custom provider):
Terminal (macOS)
launchctl setenv SUBPOOL_API_KEY "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"
Step 4 — quit ChatGPT (Desktop App) completely (not just the window), reopen it, and go to the Codex tab.
Step 1 — create/edit %USERPROFILE%\.codex\auth.json:
%USERPROFILE%\.codex\auth.json
{
"auth_mode": "apikey",
"OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"
}
Step 2 — create/edit %USERPROFILE%\.codex\config.toml. env_key and requires_openai_auth = false are required — without them, a machine that has ever done `codex login` with a ChatGPT account gets a 401 missing API key error even with the right key:
%USERPROFILE%\.codex\config.toml
model = "switch-default" model_provider = "subpool" [model_providers.subpool] name = "SubPool" base_url = "/v1" wire_api = "responses" env_key = "SUBPOOL_API_KEY" requires_openai_auth = false
Step 3 — set the SUBPOOL_API_KEY environment variable (run in PowerShell, no admin rights needed):
PowerShell
[Environment]::SetEnvironmentVariable('SUBPOOL_API_KEY', 'sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx', 'User')
Step 4 — quit ChatGPT (Desktop App) completely and reopen it to apply the new config.
401 missing API key even with the right key
If this machine has ever done `codex login` with a ChatGPT account, the app prefers that login state and won't attach Authorization to requests for a custom provider based on auth.json alone — even with the correct key entered. The surest fix is to sign out before configuring: run codex logout (if Codex CLI is installed) or sign out directly in the app. The Quick install script above already prompts for this and handles the config side; doing it manually, make sure you have both the env_key/requires_openai_auth lines in config.toml AND the environment variable step above — missing either one still causes the error.
Why it shares config with Codex CLI
Per OpenAI's official docs (learn.chatgpt.com): the desktop app, CLI, and VS Code extension all use the same cached login mechanism and config file — editing it once applies to all three, no need to repeat this per tool.
Check the model after opening the Codex tab
After configuring and opening the Codex tab, if the model shown is Custom, that's correct — use it as-is. Do NOT switch to a different model from the built-in list — switching makes the app fall back to OpenAI's default provider (no longer going through SubPool), which won't work.
Verify Connection
Open the Codex tab in ChatGPT (Desktop App), start a new session, and send a short message. A normal reply (no auth error) confirms it's talking to SubPool.
Back to all tools
SubPool Integrations
OpenCode CLI
Open-source multi-provider terminal coding agent
Endpoint: /v1/chat/completions
1
Prerequisites
- OpenCode CLI installed.
2
Choose your OS
3
Choose how to set up
Fastest way
about 1 minute
Paste the single line below into a command window and press Enter. The script asks for your API key and model, then writes the config for you. You never have to find a hidden folder or edit JSON, and any existing file is backed up before it is replaced.
Step 1 — Open Terminal: press Cmd + Space, type Terminal, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
Terminal (macOS)
curl -fsSL /setup/opencode/opencode.sh | bash
Step 1 — Open PowerShell: press the Windows key, type powershell, press Enter.
Step 2 — In the window that just opened, paste the command below and press Enter:
PowerShell (Windows)
irm /setup/opencode/opencode.ps1 | iex
- Recommended: create the global configuration at ~/.config/opencode/opencode.json to use SubPool in every project. Use ./opencode.json only for project-specific configuration.
- Declare the subpool provider as shown below. Keep npm set to @ai-sdk/openai-compatible and include models because OpenCode does not automatically load them from /v1/models.
- Replace the sample API key with your SubPool key, save the file, then run opencode. The global configuration is available from every directory.
~/.config/opencode/opencode.json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"subpool": {
"npm": "@ai-sdk/openai-compatible",
"name": "SubPool",
"options": {
"baseURL": "/v1",
"apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxx"
},
"models": {
"gpt-5-6-sol": {
"name": "GPT-5.6 Sol"
},
"gpt-5-6-terra": {
"name": "GPT-5.6 Terra"
},
"gpt-5-6-luna": {
"name": "GPT-5.6 Luna"
},
"claude-sonnet-5": {
"name": "Claude Sonnet 5"
},
"gemini-3-6-flash-high": {
"name": "Gemini 3.6 Flash High"
}
}
}
}
}
Verify Connection
Run opencode models subpool or use /models in the TUI. If the provider is missing, check provider.subpool and the models section in opencode.json.
Back to all tools
SubPool Integrations
Cursor IDE
AI-native IDE based on VS Code
Endpoint: /v1/chat/completions
Prerequisites
- Latest version of Cursor IDE installed.
- SubPool Key created in advance.
Configuration Steps
- Open Cursor → top right or menu Cursor → Settings → Cursor Settings (Cmd + , on macOS, Ctrl + , on Windows/Linux).
- In Settings window, select Models tab on left sidebar.
- Scroll down to API Keys, find OpenAI API Key — paste your SubPool key.
- Enable Override OpenAI Base URL switch, enter official Base URL (ending with /v1).
- Click Verify (if present) or close Settings — Cursor tests key automatically.
- Open AI chat (Cmd/Ctrl + L), select Add model if needed, type exact Model ID.
Cursor Settings → Models
OpenAI Base URL: /v1 OpenAI API Key: sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx
Verify Connection
Open chat panel, send a test prompt. Normal response confirms active connection.
Note
Cursor caches verified models — if you change Base URL or key, delete old model entries and re-add them.
Back to all tools
SubPool Integrations
Cline
VS Code extension coding agent
Endpoint: /v1/chat/completions
Prerequisites
- VS Code and Cline extension installed.
- Cline stores settings in 2 JSON files — editing directly on disk is faster and reliable.
Configuration Steps
- Quit VS Code completely before editing files.
- Edit ~/.cline/data/globalState.json for provider and model configuration.
- Edit ~/.cline/data/secrets.json for API key declaration.
- Reopen VS Code and confirm active model in Cline panel.
~/.cline/data/globalState.json
{
"actModeApiProvider": "openai",
"planModeApiProvider": "openai",
"openAiBaseUrl": "",
"openAiModelId": "switch-default",
"planModeOpenAiModelId": "switch-default"
}
~/.cline/data/secrets.json
{
"openAiApiKey": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"
}
Verify Connection
Send a prompt in Cline panel. Response with tool execution indicates success.
Note
openAiBaseUrl here must NOT include /v1 suffix — Cline appends it automatically.
Back to all tools
SubPool Integrations
Continue
Autocomplete & chat extension for VS Code / JetBrains
Endpoint: /v1/chat/completions
Prerequisites
- Continue extension installed in VS Code or JetBrains.
Configuration Steps
- Open Continue settings or ~/.continue/config.json.
- Add SubPool configuration object to models array.
- Save file — Continue auto-reloads configuration.
- Select SubPool model from Continue chat dropdown.
~/.continue/config.json
{
"models": [
{
"title": "SubPool",
"provider": "openai",
"model": "switch-default",
"apiBase": "/v1",
"apiKey": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"
}
]
}
Verify Connection
Send a chat prompt in Continue. Streaming response confirms success.
Back to all tools
SubPool Integrations
Hermes Agent
YAML + .env configured coding agent
Endpoint: /v1/chat/completions
Prerequisites
- Hermes Agent installed.
- Hermes separates config (YAML) and secrets (.env) — edit both.
Configuration Steps
- Configure ~/.hermes/config.yaml for model and custom provider.
- Configure ~/.hermes/.env with OPENAI_API_KEY.
- Restart Hermes Agent.
~/.hermes/config.yaml
model: default: "switch-default" provider: "custom" base_url: "/v1"
~/.hermes/.env
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx
Verify Connection
Run Hermes Agent and send a prompt. No auth errors confirms connection.
Back to all tools
SubPool Integrations
OpenClaw
Multi-agent framework configured via JSON
Endpoint: /v1/chat/completions
Prerequisites
- OpenClaw framework installed.
Configuration Steps
- Open/create ~/.openclaw/openclaw.json.
- Declare subpool provider in models.providers and set primary model to subpool/custom.
- Specify exact Model ID for both id and name.
- Restart OpenClaw.
~/.openclaw/openclaw.json
{
"agents": {
"defaults": {
"model": {
"primary": "subpool/custom"
}
}
},
"models": {
"providers": {
"subpool": {
"baseUrl": "/v1",
"apiKey": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx",
"apiType": "openai",
"models": [{ "id": "switch-default", "name": "switch-default" }]
}
}
}
}
Verify Connection
Run default agent and verify subpool provider log activity.
Back to all tools
SubPool Integrations
Qwen Code CLI
Alibaba terminal coding agent, OpenAI standard
Endpoint: /v1/chat/completions
Prerequisites
- Qwen Code installed via npm: npm install -g @qwen-code/qwen-code
Configuration Steps
- Open/create ~/.qwen/settings.json.
- Set security.auth.selectedType to openai and paste SubPool key into openaiApiKey.
- Set model.openaiBaseUrl and model.name.
- Run qwen in terminal.
~/.qwen/settings.json
{
"security": {
"auth": {
"selectedType": "openai",
"openaiApiKey": "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx"
}
},
"model": {
"openaiBaseUrl": "/v1",
"name": "switch-default"
}
}
Verify Connection
Run qwen and send a prompt. Normal response confirms connection.
Back to all tools
SubPool Integrations
DeepSeek CLI
TOML configured CLI, OpenAI standard
Endpoint: /v1/chat/completions
Prerequisites
- DeepSeek CLI installed.
Configuration Steps
- Open/create ~/.deepseek/config.toml.
- Declare [providers.openai] table with base_url, api_key, model.
- Save file and restart DeepSeek CLI.
~/.deepseek/config.toml
[providers.openai] base_url = "/v1" api_key = "sk-xxxxxxxxxxxxxxxx-xxxxxx-xxxxxxxx" model = "switch-default"
Verify Connection
Open new CLI session after saving configuration.
Common Errors — Applies to All Tools
All tools listed above authenticate through the same SubPool gateway, so the errors below present identically whether you use Cursor, Codex, or any other tool. Read the error message to identify the root cause instantly.
| Error Message | HTTP Code | Root Cause | Fix / Solution |
|---|---|---|---|
| missing API key: provide Authorization: Bearer <key> or x-api-key: <key> | 401 | Request missing authentication header — key not configured or empty. | Check tool configuration file and paste key into correct field. |
| invalid api key | 401 | Key header present but not matching any active key — invalid or revoked key. | Create new key at Manage API Keys page and paste. |
| api key expired | 403 | Quota/prepaid key has expired. | Create new key or switch to pay-as-you-go credit key. |
| api key quota exhausted | 403 | Quota key token allowance exhausted. | Create new quota key or top up credit balance. |
| insufficient balance | 402 | Valid key but account balance insufficient for request. | Top up account balance at Topup page. |
Quick Error Isolation Tip
Before inspecting tool settings, make a direct curl call to the endpoint with your key. If curl succeeds but the tool fails, the issue is strictly inside local tool configuration, not your SubPool account.