How to connect Pi to the Tokenator API

What you end up with

Once configured, Pi stops talking to its default provider and sends every request to Tokenator. Billing comes out of your key's token limit, and the list of available models is defined by the key rather than by the tool.

Requirements and supported operating systems

• Windows 10/11, macOS 12+, or a modern 64-bit Linux.
• Outbound HTTPS access to the Tokenator domain.
• A Tokenator API key that looks like sk-your-tokenator-key.

You need Node.js with npm and a terminal. The file with custom providers is created by hand, in any editor.

Installing Pi

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts disables the dependency lifecycle scripts — a normal Pi install does not need them. The agent is started with pi from the project directory.

Setting up Tokenator

1. Register in your account and buy a token bundle.
2. The key appears in the account right after the payment is confirmed — copy it whole, including the prefix.
3. The examples below use the placeholder sk-your-tokenator-key. Never publish a real key in repositories or screenshots.

Configuration

1. Create ~/.pi/agent/models.json; on Windows that is %USERPROFILE%\.pi\agent\models.json.
2. Describe the provider in it: address, protocol, key and the model list.
3. Put the key into the TOKENATOR_API_KEY environment variable — the file keeps only a reference to it.
4. Run pi and open /model (or Ctrl+L): the file is re-read every time the picker opens.

{
  "providers": {
    "tokenator": {
      "baseUrl": "https://api.tokenator.top/v1",
      "api": "openai-completions",
      "apiKey": "$TOKENATOR_API_KEY",
      "models": [
        { "id": "gpt-5.5" }
      ]
    }
  }
}

The only required field on a model is id. The rest (name, contextWindow, maxTokens, input, cost) shape how the model is displayed and accounted for in the UI and are optional.

Your first request

Before starting the tool it helps to confirm that the key and the model both work. A single curl request answers both questions.

curl https://api.tokenator.top/v1/chat/completions \
  -H "Authorization: Bearer sk-your-tokenator-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "ping"}]
  }'

cd /path/to/project
pi

Open /model (or Ctrl+L) and pick a model of the tokenator provider. Ctrl+S in the picker saves the highlighted model as the startup default.

A successful response means the key is valid, the model is allowed for it and the upstream is reachable. Usage appears in your account right after the request.

Switching models

Every model is an entry of the models array in ~/.pi/agent/models.json. The file is re-read when /model opens, so a newly added model shows up in the picker without restarting the agent.

Examples of model IDs available right now:

• claude-haiku-4-5
• claude-opus-4-6
• claude-opus-4-7
• claude-sonnet-4-6
• gpt-5.5
• deepseek-v4-pro

Current IDs and specs live in the AI model catalog, which also shows which models are available right now. The model comparison helps choose between close options.

Configuring reasoning

A reasoning model is marked in models.json with "reasoning": true. If the server does not accept the reasoning_effort field, set "supportsReasoningEffort": false in the provider's compat block; if it does not understand the developer role, set "supportsDeveloperRole": false and the system prompt is sent as a plain system message instead. compat can be set on the provider for all its models or on a single model.

The key's reasoning switch in your account works independently of the tool, and thinking is billed as output tokens.

Common errors and how to fix them

FAQ

Read next