Use AI Hub with Pi
Connect the Pi terminal coding agent to AI Hub over Chat Completions with a custom provider entry in models.json.
Pi moved from @mariozechner/pi-coding-agent (0.x) to @earendil-works/pi-coding-agent (1.x). In 1.x, models.json resolves an environment variable only when prefixed with $ ("$BELIVE_TOKENHUB_API_KEY"). In legacy 0.x, write the bare variable name ("BELIVE_TOKENHUB_API_KEY") without $, and check which pi so an older global install does not shadow npx.
1. Install Pi and prepare your key
Install the 1.x CLI package and confirm which binary is first on your PATH:
npm install -g @earendil-works/pi-coding-agent@1.5.2 which pi pi --version
Create a dedicated workspace inference key in API keys in this AI Hub environment and set a monthly spend cap. Load the secret into BELIVE_TOKENHUB_API_KEY without saving it in shell history:
printf 'AI Hub API key: ' read -r -s BELIVE_TOKENHUB_API_KEY printf '\n' export BELIVE_TOKENHUB_API_KEY
2. Configure ~/.pi/agent/models.json
Create or merge ~/.pi/agent/models.json with a belive-aihub provider over openai-completions:
{ "providers": { "belive-aihub": { "baseUrl": "https://tokenhub-api.belive.sg/api/v1", "api": "openai-completions", "apiKey": "$BELIVE_TOKENHUB_API_KEY", "models": [ { "id": "qwen/qwen3.8-flash", "name": "Qwen3.8 Flash", "reasoning": true, "input": ["text", "image"], "contextWindow": 1000000, "maxTokens": 32768, "cost": { "input": 0.1425, "output": 0.4465, "cacheRead": 0.0152, "cacheWrite": 0.19 }, "compat": { "supportsDeveloperRole": false, "thinkingFormat": "qwen", "supportsReasoningEffort": false } }, { "id": "qwen/qwen3.8-max", "name": "Qwen3.8 Max", "reasoning": true, "input": ["text", "image"], "contextWindow": 1000000, "maxTokens": 32768, "cost": { "input": 1.9, "output": 5.7, "cacheRead": 0.2375, "cacheWrite": 2.375 }, "compat": { "supportsDeveloperRole": false, "thinkingFormat": "qwen", "supportsReasoningEffort": false } }, { "id": "deepseek/deepseek-v4.1-flash-1017", "name": "DeepSeek V4.1 Flash", "reasoning": true, "input": ["text", "image"], "contextWindow": 1024000, "maxTokens": 32768, "cost": { "input": 0.144, "output": 0.576, "cacheRead": 0.0029, "cacheWrite": 0 }, "thinkingLevelMap": { "off": "none", "xhigh": "xhigh" }, "compat": { "supportsDeveloperRole": false } } ] } } }
- Transport (
"api": "openai-completions"): Dispatches every listed model tohttps://tokenhub-api.belive.sg/api/v1/chat/completions. Keep this transport; Pi'sopenai-responsesandanthropic-messagesadapters are not covered by this setup. - Thinking controls (
thinkingFormatandthinkingLevelMap):- On
qwen/qwen3.8-flashandqwen/qwen3.8-max,thinkingFormat: "qwen"withsupportsReasoningEffort: falsemaps--thinking offvs any active--thinkingflag to DashScope's binaryenable_thinking: falseortruefield. DashScope accepts top-levelreasoning_effortwithout error, whereas the catalogue publishesenable_thinkingandthinking_budget. - On
deepseek/deepseek-v4.1-flash-1017, Pi defaults to OpenAI-stylereasoning_effort:--thinking minimalthrough--thinking xhighare accepted ("xhigh": "xhigh"unlocksxhigh), and"off": "none"maps--thinking offtoreasoning_effort: "none", which disables thinking (omittingreasoning_effortleaves thinking enabled by default).
- On
supportsDeveloperRole: false: Sends system instructions asrole: "system". This flag is optional: AI Hub accepts thedeveloperrole on Qwen routes and sends it assystem. Keeping it is harmless.- Local
costestimates: Pi usescost(USD per 1M tokens) only to display local session estimates;cacheWrite: 0ondeepseek/deepseek-v4.1-flash-1017reflects that the catalogue publishes no separate cache-write rate for that model. Values inmodels.jsonare static and can drift when catalogue prices change — refresh them fromhttps://tokenhub-api.belive.sg/api/v1/modelsor Models, and check Activity for actual usage and recorded cost.
3. Run Pi in print or interactive mode
Run a single non-interactive turn (-p) with local file and shell tools:
pi --provider belive-aihub --model qwen/qwen3.8-flash --thinking low \ -p "Read package.json and summarize its scripts in two bullets."
Switch to deepseek/deepseek-v4.1-flash-1017 or turn thinking off for fast edits:
pi --provider belive-aihub --model deepseek/deepseek-v4.1-flash-1017 --thinking off \ -p "Run node -v and print only the version string."
Start an interactive terminal session in your project directory:
pi --provider belive-aihub --model qwen/qwen3.8-flashInside the interactive session, use /model to switch between configured belive-aihub models and /thinking to toggle reasoning.
Troubleshooting
401authentication error: Checkpi --versionandwhich pi.@earendil-works/pi-coding-agent(1.x) expects"apiKey": "$BELIVE_TOKENHUB_API_KEY", whereas legacy@mariozechner/pi-coding-agent(0.x) sends the literal$prefix unless written as"BELIVE_TOKENHUB_API_KEY".- Raw
<function=…>text during streaming tool turns onqwen/qwen3-coder-flash: Preferqwen/qwen3.8-flashorqwen/qwen3.8-maxfor streaming agent tool calls until a later AI Hub release fixes this. - Model missing or rejected: Copy exact
author/slugIDs from Models and confirm your inference key has no model allowlist excluding the chosen ID.