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.

View tool setup guides

OpenAI Chat Completions

The API follows the OpenAI API format and supports text generation, SSE streaming, tool/function calling, and vision.

POST /v1/chat/completions

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.

POST /v1/messages

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 the messages.
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.

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.

Available models

—

Providers

—

Capability types

—

Models by provider

See the active catalog grouped by provider, with higher-priority models first.

Catalog →

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.

Sort

Model	Provider	Input	Output	Cache write	Cache read

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

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

Install extension on Visual Studio Code

Choose your OS

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

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"
  }
}

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

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.

Choose your OS

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.

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

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>.json file for the profile you use — with a single profile there is exactly one .json in 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 at C:\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>.json files; 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

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.

Choose your OS

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/codex/codex.sh | bash

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.

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

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.

Choose your OS

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/chatgpt-app/chatgpt-app.sh | bash

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.

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

Prerequisites

OpenCode CLI installed.

Choose your OS

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/opencode/opencode.sh | bash

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.

API Documentation & Technical Reference

Quickstart & Authentication

1 Core connection settings

2 Request authentication headers

3 Send your first connection test request

Integrating an IDE or AI coding agent?

OpenAI Chat Completions

SDK integration examples

Request body parameters

SSE streaming & reasoning models

Anthropic Messages API

Anthropic SDK integration example

Anthropic parameters & extended thinking

Computer vision & multimodal input

1 Overview & use cases

2 OpenAI vision format (cURL, Python & Base64)

3 Anthropic vision format (POST /v1/messages)

4 Supported formats & token cost optimization

Error codes & troubleshooting

1 Standard error response JSON

2 HTTP status codes

3 Production error-handling recommendations

Models by provider

Capability coverage

Catalog

Pricing

AI model pricing

Filters:

Developer Tools & AI Coding Agent Guides

Before you start — 3 things you need ready

Select a tool to view detailed guide

Claude Code

Requirement

Choose your OS

Choose how to set up

Verify Connection

Claude (Desktop app)

Prerequisites

Choose your OS

Connect the Gateway for the first time

Choose how to set up

Verify Connection

Codex CLI

Prerequisites

Choose your OS

Choose how to set up

Verify Connection

ChatGPT (Desktop app)

Prerequisites

Choose your OS

Choose how to set up

Verify Connection

OpenCode CLI

Prerequisites

Choose your OS

Choose how to set up

Verify Connection

Cursor IDE

Prerequisites

Configuration Steps

Verify Connection

Cline

Prerequisites

Configuration Steps

Verify Connection

Continue

Prerequisites

Configuration Steps

Verify Connection

Hermes Agent

Prerequisites

Configuration Steps

Verify Connection

OpenClaw

Prerequisites

Configuration Steps

Verify Connection

Qwen Code CLI

Prerequisites

Configuration Steps