pi-provider-freellmapi

A pi extension that registers the FreeLLM API gateway (freeapi.n.cofire.cn) as three pi providers — openai-completions, openai-responses, and anthropic-messages — with automatic model discovery and custom tools for non-chat endpoints.

It only exposes models your API key can actually use (the gateway reports ~250 models, but most are available: false for a free key — this extension filters those out), and it reads each model's real context window and reasoning/vision capabilities.

Install

pi install npm:pi-provider-freellmapi

Providers

The extension registers three pi providers sharing the same model list from the gateway so you can pick whichever API shape suits your use case:

Provider	API type	Endpoint
freellmapi	openai-completions	/v1/chat/completions
freellmapi-responses	openai-responses	/v1/responses
freellmapi-anthropic	anthropic-messages	/v1/messages

Select a provider in the TUI with /model, or from the CLI:

pi --provider freellmapi --model auto
pi --provider freellmapi-responses --model auto
pi --provider freellmapi-anthropic --model auto

Disable extra providers via the endpoints config (see below).

Configure

Copy the example config to ~/.pi/agent/freellmapi.json and fill in your key:

cp "$(pi config-dir 2>/dev/null || echo ~/.pi/agent)/freellmapi.json" freellmapi.example.json
# or just:
mkdir -p ~/.pi/agent
cp freellmapi.example.json ~/.pi/agent/freellmapi.json

{
  "name": "freellmapi",
  "label": "FreeLLM API",
  "baseUrl": "https://freeapi.n.cofire.cn",
  "apiKey": "$FREELLM_API_KEY",
  "fetchModels": true,
  "contextWindow": 131072,
  "maxTokens": 16384,
  "compat": { "supportsDeveloperRole": false },
  "endpoints": {
    "embeddings":     { "enabled": true, "model": "auto" },
    "images":         { "enabled": true, "model": "auto" },
    "videos":         { "enabled": true, "model": "inkling" },
    "speech":         { "enabled": true, "model": "auto" },
    "transcriptions": { "enabled": true, "model": "whisper-1" },
    "responses":      { "enabled": true },
    "anthropic":      { "enabled": true }
  }
}

The apiKey supports pi's value syntax: a literal, $ENV_VAR, ${ENV_VAR}, or !command. You can also skip the config file entirely and set either env var.

Environment variables (fallback chain, config file wins):

Variable	Purpose
FREELLM_API_KEY	API key
FREELLM_API_BASE_URL	Override the base URL (default: https://freeapi.n.cofire.cn)
PI_FREELLMAPI_CONFIG	Path to config JSON (default: ~/.pi/agent/freellmapi.json)

• Set "fetchModels": false to use only the static models list.
• Set "endpoints": { "responses": false } to disable a provider/tool.

Endpoint tools

In addition to the chat providers, the extension registers custom tools that wrap the gateway's other OpenAI-compatible endpoints. They are enabled by default; set "enabled": false ("endpoints": { "images": false }) or set a default model per endpoint to customize them.

Tool	Endpoint	What it does
freellm_embed	POST /embeddings	Generates embeddings; writes JSON to a file
freellm_image	POST /images/generations	Generates image(s), returned inline
freellm_video	POST /videos/generations	Generates a video, polls the task, downloads the file
freellm_speech	POST /audio/speech	Synthesizes speech, writes audio to a file
freellm_transcribe	POST /audio/transcriptions	Transcribes a local path or URL, returns text

Each tool accepts an optional model argument. When omitted, the extension picks a default from (in priority order): the endpoint's model config, model ids discovered from {baseUrl}/models matching that endpoint, or a conventional OpenAI id (e.g. auto for embeddings/images/speech, inkling, whisper-1). If the gateway rejects a default, set the endpoint's model in config.

Files written by the tools land in the session working directory with freellm-* names, or an outputFile path you pass to the tool.

Config reference

Field	Default	Description
name	freellmapi	Provider id (--provider <name>)
label	FreeLLM API	Display label shown in /model
baseUrl	https://freeapi.n.cofire.cn	Base URL (auto-appends /v1)
apiKey	$FREELLM_API_KEY	API key (literal / env / command)
fetchModels	true	Discover models from {baseUrl}/models
contextWindow	131072	Fallback context window per model
maxTokens	16384	Fallback max output tokens
compat	{"supportsDeveloperRole":false}	Provider compatibility flags
models	[]	Static models (override discovered models by id)
headers	{}	Extra headers merged into every tool request
endpoints	all enabled	Per-endpoint enabled flag and default model

License

MIT