BETA

Docs
Instructions

How to connect Pi to Apily

Pi has no provider wizard: custom providers are declared in a single JSON file. The file is re-read every time you open /model, so the agent needs no restart after an edit.

Tool
Pi OpenAI-compatible
Base URL
https://apily.pro/v1
Key
$APILY_API_KEY (or inline apiKey)
Config file
~/.pi/agent/models.json

Requirements

  • Node.js with npm and a terminal.
  • The file with custom providers is created by hand, in any editor.
  • An Apily API key from your account at apily.pro.

Install Pi

Install Pi with npm and start the agent with pi from the project directory. --ignore-scripts disables dependency lifecycle scripts — a normal install does not need them.

terminal
npm install -g pi-agent --ignore-scripts
pi

Configuration

Declare the apily provider in ~/.pi/agent/models.json (on Windows: %USERPROFILE%\.pi\agent\models.json). The key is referenced as $APILY_API_KEY — a value without $ is treated as a literal rather than an environment variable name:

~/.pi/agent/models.json
{
  "providers": {
    "apily": {
      "baseUrl": "https://apily.pro/v1",
      "apiKey": "$APILY_API_KEY",
      "models": [
        { "id": "gpt-5.6-sol", "name": "GPT-5.6 Sol", "reasoning": true },
        { "id": "claude-opus-5", "name": "Claude Opus 5", "reasoning": true },
        { "id": "deepseek-v4-flash-0731", "name": "DeepSeek V4 Flash" }
      ]
    }
  }
}
terminal
export APILY_API_KEY=apily_your-api-key

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. A key can also be stored with /login or passed with --api-key when selecting the model.

Your first request

terminal
curl https://apily.pro/v1/chat/completions \
  -H "Authorization: Bearer apily_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"ping"}]}'

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

Switching models

Every model is an entry of the models array. The file is re-read when /model opens, so a newly added model shows up in the picker without restarting the agent. Examples from the Apily catalog:

  • gpt-5.6-sol · claude-opus-5 · deepseek-v4-flash-0731 · gemini-3.5-flash

Configuring reasoning

A reasoning model is marked in models.json with "reasoning": true. If you ever need compatibility switches, they live in a compat block on the provider or on a single model — e.g. "supportsReasoningEffort": false or "supportsDeveloperRole": false. Thinking is billed as output tokens.

Common errors and how to fix them

SymptomCauseFix
The model loads but stays unavailable in /modelNo auth is configured for the provider — models are visible but cannot be selected.Set apiKey in the file, store a key with /login, or pass --api-key.
The literal string APILY_API_KEY is sent to the serverA value without $ is treated as a literal.Write $APILY_API_KEY and make sure the variable is present in the environment.
The file was not picked up at allA syntax error in the JSON.Validate the file with a JSON linter and open /model again — it is re-read every time the picker opens.
401 Invalid API keyKey copied with stray spaces, truncated, or revoked.Copy the key whole from the API page in your Apily account, the apily_ prefix included.
402 Insufficient balanceYour token balance can't cover the request's estimated cost.Top up your balance on the Billing page in your Apily account.

FAQ

All guidesPreviousHermesNextOpenClaw