Docs · Integrations

opencode with TopxAI: a custom provider in opencode.json

2026-10-24

Declare TopxAI in opencode.json with @ai-sdk/openai-compatible, the base URL and the model ids, then pick them with /models.

opencode takes custom providers in opencode.json (in the project or in ~/.config/opencode/). One block with the @ai-sdk/openai-compatible package covers every TopxAI text model; a second with @ai-sdk/anthropic keeps Claude on the Messages API.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "topxai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TopxAI",
      "options": {
        "baseURL": "https://ai.topxea.com/v1",
        "apiKey": "{env:TOPXAI_API_KEY}"
      },
      "models": {
        "claude-sonnet-5-5": {
          "name": "Claude Sonnet 5.5",
          "limit": { "context": 1000000, "output": 128000 }
        },
        "gpt-6.1-sol": {
          "name": "GPT-6.1 Sol",
          "limit": { "context": 1000000, "output": 128000 }
        },
        "grok-4.7": {
          "name": "Grok 4.7",
          "limit": { "context": 500000, "output": 128000 }
        },
        "kimi-k3.1-pro": {
          "name": "Kimi K3.1 Pro",
          "limit": { "context": 1048576, "output": 131072 }
        }
      }
    },
    "topxai-claude": {
      "npm": "@ai-sdk/anthropic",
      "name": "TopxAI (Anthropic API)",
      "options": {
        "baseURL": "https://ai.topxea.com/v1",
        "apiKey": "{env:TOPXAI_API_KEY}"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "claude-opus-5-5": { "name": "Claude Opus 5.5" }
      }
    }
  }
}

Then:

export TOPXAI_API_KEY=sk-...
opencode

and choose a model with /models; the provider names appear as headings.

Notes

• {env:TOPXAI_API_KEY} reads the key from the environment; {file:~/.secrets/topxai} reads it from a file. Either keeps the key out of the config.
• The @ai-sdk/anthropic package expects a base URL ending in /v1 and appends /messages; the @ai-sdk/openai-compatible package appends /chat/completions.
• limit is what opencode uses for its context meter; the values above are the models' windows, not a TopxAI limit.
• Model ids must match the catalogue exactly; GET https://ai.topxea.com/v1/models with your key lists them.

If it fails

• 401: the key is wrong or was pasted with a space. 402: the balance is empty. 403: the model id is not sold here or is not on this key's route. See Common error responses.
• The model works in curl but not in the tool: that page lists the usual causes, one per tool.

Models: claude-sonnet-5-5, gpt-6.1-sol · Models & pricing

Related

• Connect your SDK
• Create an API key and choose a route
• The model works in curl but not in my tool
• Common error responses
• Codex CLI custom model provider: model_providers in config.toml for TopxAI
• Aider with TopxAI: OPENAI_API_BASE and the model name
• Claude Sonnet 5.5 API pricing
• GPT-6.1 Sol API pricing

Previous: Aider with TopxAI: OPENAI_API_BASE and the model name · Next: Open WebUI with TopxAI: one OpenAI connection, every model

Other languages: 简体中文