sub2api Provider
Use a sub2api-compatible API directly in VS Code Chat and GitHub Copilot Agent mode. The provider is endpoint-neutral: no server address or API key is bundled.
Highlights
- VS Code Stable 1.130+ and VS Code Insiders
- OpenAI Responses, OpenAI Chat Completions, and Anthropic Messages protocols
- Responses is the default and retains encrypted reasoning replay, stable cache routing, and GPT-5.6 cache breakpoints
- Streaming text, vision, function tools, and tool results
- Visible status-bar selectors for reasoning effort and context management
- Automatic long-context trimming plus one-click compaction of the next request
- Live request/session tokens, cache-hit rate, and optional server balance
- API keys stored in VS Code SecretStorage
Get started
- Install from the Visual Studio Marketplace or a VSIX.
- Run
sub2api: Configure Endpoint and enter your API base URL.
- Run
sub2api: Set API Key.
- Keep
sub2api.apiFormat at openai-responses, or select another compatible protocol.
- Run
sub2api: Test Connection, open Chat, and choose a model from the sub2api provider.
Stable and Insiders use separate extension installations and SecretStorage databases. Configure the endpoint and key once in each edition you use.
The sub2api.apiFormat setting controls the wire protocol:
| Setting |
Request path |
Reasoning field |
openai-responses (default) |
/v1/responses |
reasoning.effort |
openai-completions |
/v1/chat/completions |
reasoning_effort |
anthropic-messages |
/v1/messages |
Extended-thinking token budget |
A base URL receives the selected suffix automatically. A full known inference URL is replaced when you switch formats. Only HTTP and HTTPS endpoints are accepted, and credentials embedded in URLs are rejected.
Responses sends stream: true, store: false, and a stable prompt_cache_key. In the default auto mode, GPT-5.6 also receives explicit cache breakpoints; incompatible gateways retry once with implicit caching. Chat Completions uses stream_options.include_usage. Anthropic Messages sends the required Anthropic version header as well as the configured gateway key.
Reasoning selector
Click the reasoning icon in the Copilot Chat title bar, or sub2api Reasoning in the status bar to choose Model, Low, Medium, High, XHigh, or Max. The selection is forwarded on subsequent requests. “Model” follows the selected model variant or a reasoning setting supplied by VS Code.
The model picker still lists effort-specific variants. The public third-party Provider API does not expose the same native supportsReasoningEffort submenu used by VS Code's built-in Custom Endpoint editor, so the extension provides this separate visible selector.
Context and compaction
| Models |
Native input |
Native output |
Total window |
| GPT-5.3 Codex Spark |
96,000 |
32,000 |
128,000 |
| Codex Mini |
100,000 |
100,000 |
200,000 |
| GPT-5.2, GPT-5.4 Mini |
272,000 |
128,000 |
400,000 |
| GPT-5.4, GPT-5.5, GPT-5.6 variants |
922,000 |
128,000 |
1,050,000 |
The extension advertises the independent input/output limits to VS Code and reserves 8,192 input tokens by default. sub2api.maxOutputTokens defaults to 32,768.
Click the context icon in the Copilot Chat title bar, or sub2api Context in the status bar, to:
- compact the next request once by dropping the oldest 35% of serialized message items;
- enable automatic trimming (default);
- disable automatic trimming; or
- open context settings.
Automatic trimming starts at 85% of the advertised safe input limit by default. If the gateway still rejects a request for context length, the provider retries once with a smaller suffix. Trimming keeps the newest conversation content but cannot produce a semantic summary; start a fresh Chat when old details remain important.
Lower sub2api.contextWindowCap if your particular gateway exposes a smaller limit than the catalog. A larger advertised limit delays VS Code's own context management and can increase tokens sent on every Agent step.
Usage, cache, and balance
The usage status item shows spent and remaining USD allowance when /v1/usage supplies quota data; otherwise it shows the latest cache hit rate and cumulative tokens for this VS Code session. Hover it for input, cached, uncached, cache-write, output, and session totals. Click it to open the usage panel.
With sub2api.usageEndpoint: auto, the provider derives /v1/usage and refreshes it every five minutes and after completed requests. Compatible deployments can supply API-key quota (used, remaining, and limit), wallet balance, subscription daily/weekly/monthly windows, rate limits, today/total actual cost, and model statistics. If that endpoint is unavailable, request/session token metrics still work from inference responses. Status bars, hover details, selectors, notifications, and command titles automatically use Chinese when the VS Code display language starts with zh; otherwise they use English. Use a full sub2api.usageEndpoint override for deployments with a different path, or set it to an empty string to disable quota requests.
Responses cache routing is derived from endpoint host, workspace, and upstream model, so changing Max/XHigh no longer moves the conversation to a different sticky route. Tool definitions and schemas are sorted to keep reusable prefixes deterministic. In the default auto mode, GPT-5.6 requests mark up to two recent reusable user-message prefixes and use explicit-only cache writes. If an older sub2api-compatible gateway rejects those fields, the provider retries once with stable-key implicit caching and remembers that fallback for the current VS Code session.
The first request after upgrading to 1.0.5, changing models, changing tools, or compacting away an earlier breakpoint can still be a cold cache write. Later turns with the same prefix should reuse the prior breakpoint.
Privacy and security
- Keys are stored in VS Code SecretStorage, never settings.
- Prompt contents and keys are never written to logs.
- No endpoint is preconfigured or contacted before you configure one.
- Review the privacy, retention, and billing policy of your chosen endpoint.
Troubleshooting
Run sub2api: Show Logs for request metadata, protocol, model, advertised input limit, conservative estimate, cache strategy, breakpoint count, anonymized route fingerprint, usage, and server error bodies.
SUB2API_CONTEXT_WINDOW_EXCEEDED means the selected gateway limit was still exceeded. Use the sub2api Context status item, lower sub2api.contextWindowCap, or start a new chat.
SUB2API_STREAM_TERMINATED means the gateway closed SSE before the selected protocol completed. Check upstream/reverse-proxy timeouts and SSE heartbeat behavior. The provider does not blindly retry incomplete generated output because that can duplicate tokens and tool calls.
License
MIT
