Docs · Integrations

Aider with TopxAI: OPENAI_API_BASE and the model name

2026-10-28

Run aider against TopxAI with OPENAI_API_BASE=https://ai.topxea.com/v1 and --model openai/claude-sonnet-5-5, or the Anthropic variables for the Claude line.

Aider uses LiteLLM underneath. Use the openai/ prefix for TopxAI Chat Completions, or anthropic/ for Claude Messages. Model capabilities and client-version limits still apply; see the compatibility table.

OpenAI-compatible chat models

export OPENAI_API_BASE=https://ai.topxea.com/v1
export OPENAI_API_KEY=sk-...          # a TopxAI key on the Auto route
aider --model openai/claude-sonnet-5-5

Use a current chat-model ID after openai/, excluding the separate Jev, image and video APIs: openai/gpt-6.1-sol, openai/grok-4.7, openai/kimi-k3.1-pro, openai/GLM-5.3-Abliterated.

Anthropic (Claude, with prompt caching)

export ANTHROPIC_API_BASE=https://ai.topxea.com
export ANTHROPIC_API_KEY=sk-...
aider --model anthropic/claude-sonnet-5-5 --cache-prompts

For an unfamiliar model ID, Aider may not have a caching preset. Add this entry to .aider.model.settings.yml in the project root, following Aider's model settings:

- name: anthropic/claude-sonnet-5-5
  cache_control: true

Run with --cache-prompts and check that the startup model description includes prompt cache. TopxAI forwards the resulting cache breakpoints and bills cache reads and writes at the selected model and route's separate prices. Check the current cache prices and the worked billing example; the cache-read discount is not the same for every Claude model.

Model metadata

Aider warns when it has no context-window or price data for a model name. Add a .aider.model.metadata.json in your project root to provide limits and prices for Aider's estimate:

{
  "openai/claude-sonnet-5-5": {
    "max_input_tokens": 1000000,
    "max_output_tokens": 128000,
    "input_cost_per_token": 0.000001,
    "output_cost_per_token": 0.000005,
    "litellm_provider": "openai",
    "mode": "chat"
  }
}

This metadata entry applies to the exact openai/claude-sonnet-5-5 name. It includes only uncached input and output at the shared-pool prices from the model's page; it does not configure cache rates or the anthropic/ model entry. Aider's running total is an estimate; the actual charge is in the TopxAI usage log.

Persisting it

Put the same values in ~/.aider.conf.yml (model: openai/claude-sonnet-5-5, openai-api-base: https://ai.topxea.com/v1) and export the key in your shell profile. If you store the key in a custom file such as ~/.aider/oai.env, load it explicitly with aider --env-file ~/.aider/oai.env; that path is not loaded automatically. See Aider's environment-file rules.

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

Previous: Zed with TopxAI: OpenAI- and Anthropic-compatible providers · Next: opencode with TopxAI: a custom provider in opencode.json

Other languages: 简体中文