OpenCode custom provider setup for apimodels.app
OpenCode is an open-source coding agent that runs in the terminal, as a desktop app and on the web. Its built-in model catalog comes from models.dev, which does not list apimodels.app at the moment (checked 2026-11-18), so you add us as a custom provider: one OpenAI-compatible provider in opencode.json pointing at https://api.apimodels.app/v1, and one key covers GPT, Claude, DeepSeek and the rest. OpenCode 2.x and 1.x use different config keys; both versions are below, plus MCP setup and the common errors.
Configuration values you need
| Base URL | https://api.apimodels.app/v1 |
| Package (2.x) | @opencode/ai/providers/openai-compatible |
| Package (1.x) | @ai-sdk/openai-compatible |
| API key | An sk_… key from the apimodels console, kept in the APIMODELS_API_KEY env var |
| Model ids | gpt-6.2-sol · claude-fable-5-2 · deepseek-v4.1-flash |
Step 1 · Check whether you run OpenCode 2.x or 1.x
Run opencode --version. If it prints opencode v2.x, use the providers config; if it prints 1.x, use the provider config. The npm package opencode-ai currently installs 1.x (1.19.6 on 2026-11-18); @opencode/cli, the opencode.ai/v2/install script and OpenCode Desktop 2.x are 2.x.
Step 2 · Put your API key in an environment variable
# macOS / Linux (add it to ~/.zshrc or ~/.bashrc to keep it)
export APIMODELS_API_KEY="sk_…your_apimodels_key…"
# Windows (PowerShell or cmd), then open a new terminal
setx APIMODELS_API_KEY "sk_…your_apimodels_key…"No key yet? Create one in Console → API Keys. The config only names the variable, so the key never lands in opencode.json. The variable must be visible to the process that starts OpenCode: after editing your shell profile, open a new terminal and start OpenCode from there.
Step 3 · Add the provider to opencode.json
The global config lives at ~/.config/opencode/opencode.json; for one project only, use opencode.json in the project root. If you already have a config, merge the providers (or provider) block into it.
OpenCode 2.x
// ~/.config/opencode/opencode.json — OpenCode 2.x
{
"$schema": "https://opencode.ai/config.json",
"model": "apimodels/gpt-6.2-sol",
"providers": {
"apimodels": {
"name": "apimodels.app",
"env": ["APIMODELS_API_KEY"],
"package": "@opencode/ai/providers/openai-compatible",
"settings": {
"baseURL": "https://api.apimodels.app/v1"
},
"models": {
"gpt-6.2-sol": {
"name": "GPT-6.2 Sol",
"limit": { "context": 1050000, "output": 128000 }
},
"claude-fable-5-2": {
"name": "Claude Fable 5.2",
"limit": { "context": 1000000, "output": 128000 }
},
"deepseek-v4.1-flash": {
"name": "DeepSeek V4.1 Flash",
"limit": { "context": 1000000, "output": 128000 }
}
}
}
}
}OpenCode 1.x
// ~/.config/opencode/opencode.json — OpenCode 1.x
{
"$schema": "https://opencode.ai/config.json",
"model": "apimodels/gpt-6.2-sol",
"provider": {
"apimodels": {
"npm": "@ai-sdk/openai-compatible",
"name": "apimodels.app",
"options": {
"baseURL": "https://api.apimodels.app/v1",
"apiKey": "{env:APIMODELS_API_KEY}"
},
"models": {
"gpt-6.2-sol": {
"name": "GPT-6.2 Sol",
"limit": { "context": 1050000, "output": 128000 }
},
"claude-fable-5-2": {
"name": "Claude Fable 5.2",
"limit": { "context": 1000000, "output": 128000 }
},
"deepseek-v4.1-flash": {
"name": "DeepSeek V4.1 Flash",
"limit": { "context": 1000000, "output": 128000 }
}
}
}
}
}- Each key under models is the model id sent to us and must match the id on our model page exactly; inside OpenCode you refer to it as apimodels/<model id>.
- limit tells OpenCode how much context is left; without it, 2.x assumes a 200K context and 32K output.
- On 1.x you can drop apiKey instead: run /connect in OpenCode (or opencode auth login), scroll to Other, enter apimodels as the provider id and paste the key. The id must match the provider name in the config.
- 2.x also reads the 1.x provider block, but early 2.x builds (such as 2.1.4) did not; write new configs with providers.
Step 4 · Pick a model with /models
Restart OpenCode, run /models and pick a model under apimodels. A coding agent edits files through function calls, and all three below support tool calling. To add another model, put its id under models; the full list is at the model catalog. Prices are on each model page.
| GPT-6.2 Sol | gpt-6.2-sol | A sensible default for everyday coding; 1.05M context, function calling; rejects reasoning_effort none. |
| Claude Fable 5.2 | claude-fable-5-2 | Long, multi-file changes; 1M context, 128K output, thinking always on. |
| DeepSeek V4.1 Flash | deepseek-v4.1-flash | Fast; suits many small edits and questions; 1M context, tool calling, billed on DeepSeek's peak / off-peak schedule. |
Reasoning effort
Models from a custom provider are not in OpenCode's built-in catalog, so they come without ready-made reasoning variants; define them on the model yourself: settings plus a variants array on 2.x, options plus a variants object on 1.x. GPT-6.2 Sol takes low, medium or high and rejects none.
// 2.x: inside providers.apimodels.models
"gpt-6.2-sol": {
"name": "GPT-6.2 Sol",
"settings": { "reasoningEffort": "medium" },
"variants": [
{ "id": "low", "settings": { "reasoningEffort": "low" } },
{ "id": "high", "settings": { "reasoningEffort": "high" } }
]
}
// pick a variant per run: opencode run --model apimodels/gpt-6.2-sol#high "…"// 1.x: inside provider.apimodels.models
"gpt-6.2-sol": {
"name": "GPT-6.2 Sol",
"options": { "reasoningEffort": "medium" },
"variants": {
"low": { "reasoningEffort": "low" },
"high": { "reasoningEffort": "high" }
}
}Add the apimodels MCP server for images and video
The provider above covers chat models only. Image, video and speech models reach OpenCode as tools through our remote MCP server, https://api.apimodels.app/mcp (generate_image, generate_video, text_to_speech and more). It supports OAuth, which OpenCode uses for remote servers by default: sign in to apimodels.app in the browser and click Authorize.
# OpenCode 2.x: writes mcp.servers.apimodels into your global config
opencode mcp add apimodels --global --url https://api.apimodels.app/mcp
# then sign in once: run /mcps inside OpenCode and pick apimodels, or
opencode mcp auth apimodels// OpenCode 1.x: add to opencode.json, then run: opencode mcp auth apimodels
"mcp": {
"apimodels": {
"type": "remote",
"url": "https://api.apimodels.app/mcp",
"timeout": 120000
}
}On 1.x, timeout is set to 120000 ms because the video tool waits up to 50 seconds per call before handing back a task id. To skip the browser sign-in, turn OAuth off and send your key in a header:
// No browser sign-in: send your key instead (2.x: under mcp.servers; 1.x: under mcp)
"apimodels": {
"type": "remote",
"url": "https://api.apimodels.app/mcp",
"oauth": false,
"headers": { "Authorization": "Bearer {env:APIMODELS_API_KEY}" }
}Tools and billing: /docs/mcp. Generations bill at each model page's price; failed ones are not charged.
One-click import with CC Switch
CC Switch manages OpenCode providers. If you would rather not edit opencode.json by hand, it can add apimodels to OpenCode in one click; see the CC Switch guide.
Common errors
| Symptom | Cause / fix |
|---|---|
| Custom providers are unavailable on this server | Comes from the "add custom provider" dialog in 2.x Desktop / web settings, whose save action is not finished in released 2.x builds; your URL and key are not the problem (anomalyco/opencode#50650, still open on 2026-11-18). Write the providers config above into ~/.config/opencode/opencode.json instead. |
| apimodels missing from /models | Config keys do not match your version (providers on 2.x, provider on 1.x), the JSON does not parse, or OpenCode was not restarted (2.x also has opencode reload). Check with opencode models (on 1.x: opencode models apimodels). |
| Model unavailable: apimodels/… | The model is not under models, or its key has a typo. Add the model id to models exactly as written. |
| 401 / Invalid or missing API key | The OpenCode process cannot see APIMODELS_API_KEY, or the key was deleted. Start OpenCode from a fresh terminal, or create a new key in the console. |
| 404 | Wrong baseURL. It must be https://api.apimodels.app/v1, without /chat/completions on the end. |
| 400 naming the model | The model id has a typo or is not a chat model. Compare with the id on the model page, or list all ids with GET https://api.apimodels.app/v1/models. |
Sources (checked 2026-11-18): OpenCode docs Providers (2.x) · Providers (1.x) · MCP servers · Models · issue #50650. OpenCode is an open-source project by anomalyco and is not affiliated with apimodels.app.
FAQ
How do I use a relay API such as apimodels.app for GPT models in OpenCode?
Add the relay as a custom provider in opencode.json: base URL https://api.apimodels.app/v1, your apimodels sk_… key, and the model ids you want under models, such as gpt-6.2-sol, claude-fable-5-2 and deepseek-v4.1-flash. On OpenCode 2.x it goes under providers with package @opencode/ai/providers/openai-compatible and settings.baseURL; on 1.x under provider with npm @ai-sdk/openai-compatible and options.baseURL. Restart OpenCode and pick apimodels/gpt-6.2-sol in /models. GPT, Claude and DeepSeek models all use the same URL and key.
What does an OpenCode custom provider config look like, and is it the same in 1.x and 2.x?
No. OpenCode 2.x, the version its current docs describe, uses a providers object where each provider has package, settings.baseURL, env and models. 1.x uses provider with npm, options.baseURL, options.apiKey and models. Run opencode --version: opencode v2.x means providers, 1.x means provider. 2.x also reads the older provider block, but early 2.x builds such as 2.1.4 did not, so write new configs with providers. The keys under models are the model ids sent to the API and must match exactly. Both configs on this page load in OpenCode 1.19.6 and 2.3.2.
Where does the API key go for an OpenCode custom provider?
Keep it in an environment variable, e.g. export APIMODELS_API_KEY="sk_…". On 2.x reference it with "env": ["APIMODELS_API_KEY"] in the provider; on 1.x with "apiKey": "{env:APIMODELS_API_KEY}" under options. On 1.x you can instead run /connect (or opencode auth login), choose Other, enter apimodels as the provider id and paste the key, which is stored in ~/.local/share/opencode/auth.json; the id must match the provider name in the config. The variable has to be visible to the process that starts OpenCode, so open a new terminal after setting it.
What does "Custom providers are unavailable on this server" mean in OpenCode?
It comes from the "add custom provider" dialog in the OpenCode 2.x desktop and web settings, whose save action is not finished in released 2.x builds, so it fails whatever URL or key you enter (tracked in anomalyco/opencode issue #50650, still open on 18 November 2026). Write the providers block into ~/.config/opencode/opencode.json yourself instead; the same server loads it, and the models appear in /models.
Why is my OpenCode custom provider not showing?
Check in this order: the config keys match your version (providers on 2.x, provider on 1.x); the file parses as JSON and sits at ~/.config/opencode/opencode.json or opencode.json in the project root; every model is listed under models with its exact id; OpenCode was restarted (2.x also has opencode reload). Then run opencode models (on 1.x, opencode models apimodels) and look for apimodels/… entries. "Model unavailable: apimodels/x" means x is not under models.
How do I set reasoning effort for a custom provider in OpenCode?
Models from a custom provider are not in OpenCode's built-in catalog, so they have no ready-made reasoning variants; define them on the model. On 2.x add "settings": { "reasoningEffort": "high" }, or a variants array such as low and high, and select one with apimodels/gpt-6.2-sol#high. On 1.x add "options": { "reasoningEffort": "high" }, or a variants object. GPT-6.2 Sol takes low, medium or high and rejects none.
How do I add an MCP server in OpenCode, and can it generate images and video with apimodels?
Yes. The apimodels remote MCP server is https://api.apimodels.app/mcp and provides generate_image, generate_video, text_to_speech and more. On 2.x run opencode mcp add apimodels --global --url https://api.apimodels.app/mcp, then sign in from /mcps or with opencode mcp auth apimodels. On 1.x add { "type": "remote", "url": "https://api.apimodels.app/mcp" } under mcp in opencode.json and run opencode mcp auth apimodels. To skip the browser sign-in, set "oauth": false and send "Authorization": "Bearer {env:APIMODELS_API_KEY}" in headers. Generations bill at each model page's price; failed ones are not charged.