Guides

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:

bash
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:

bash
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:

json
{
  "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 to https://tokenhub-api.belive.sg/api/v1/chat/completions. Keep this transport; Pi's openai-responses and anthropic-messages adapters are not covered by this setup.
  • Thinking controls (thinkingFormat and thinkingLevelMap):
    • On qwen/qwen3.8-flash and qwen/qwen3.8-max, thinkingFormat: "qwen" with supportsReasoningEffort: false maps --thinking off vs any active --thinking flag to DashScope's binary enable_thinking: false or true field. DashScope accepts top-level reasoning_effort without error, whereas the catalogue publishes enable_thinking and thinking_budget.
    • On deepseek/deepseek-v4.1-flash-1017, Pi defaults to OpenAI-style reasoning_effort: --thinking minimal through --thinking xhigh are accepted ("xhigh": "xhigh" unlocks xhigh), and "off": "none" maps --thinking off to reasoning_effort: "none", which disables thinking (omitting reasoning_effort leaves thinking enabled by default).
  • supportsDeveloperRole: false: Sends system instructions as role: "system". This flag is optional: AI Hub accepts the developer role on Qwen routes and sends it as system. Keeping it is harmless.
  • Local cost estimates: Pi uses cost (USD per 1M tokens) only to display local session estimates; cacheWrite: 0 on deepseek/deepseek-v4.1-flash-1017 reflects that the catalogue publishes no separate cache-write rate for that model. Values in models.json are static and can drift when catalogue prices change — refresh them from https://tokenhub-api.belive.sg/api/v1/models or 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:

bash
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:

bash
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:

bash
pi --provider belive-aihub --model qwen/qwen3.8-flash

Inside the interactive session, use /model to switch between configured belive-aihub models and /thinking to toggle reasoning.

Troubleshooting

  • 401 authentication error: Check pi --version and which 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 on qwen/qwen3-coder-flash: Prefer qwen/qwen3.8-flash or qwen/qwen3.8-max for streaming agent tool calls until a later AI Hub release fixes this.
  • Model missing or rejected: Copy exact author/slug IDs from Models and confirm your inference key has no model allowlist excluding the chosen ID.