---
slug: "h00w-pi-provider-aihubmix"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/hwei/pi-provider-aihubmix@main/README.md"
repo: "https://github.com/hwei/pi-provider-aihubmix"
source_file: "README.md"
branch: "main"
---
# @h00w/pi-provider-aihubmix

[![npm version](https://img.shields.io/npm/v/@h00w/pi-provider-aihubmix.svg)](https://www.npmjs.com/package/@h00w/pi-provider-aihubmix)
[![npm downloads](https://img.shields.io/npm/dm/@h00w/pi-provider-aihubmix.svg)](https://www.npmjs.com/package/@h00w/pi-provider-aihubmix)
[![license](https://img.shields.io/npm/l/@h00w/pi-provider-aihubmix.svg)](https://www.npmjs.com/package/@h00w/pi-provider-aihubmix)
[![node](https://img.shields.io/node/v/@h00w/pi-provider-aihubmix.svg)](https://www.npmjs.com/package/@h00w/pi-provider-aihubmix)
[![GitHub](https://img.shields.io/badge/GitHub-hwei%2Fpi--provider--aihubmix-blue?logo=github)](https://github.com/hwei/pi-provider-aihubmix)

Pi provider extension that auto-registers [AIHubMix](https://aihubmix.com) models for the [pi coding agent](https://pi.dev).

- Pulls the live model catalog from AIHubMix
- Registers chat/agent models under the `aihubmix` provider
- Routes Claude → Anthropic Messages, Gemini → Google Generative AI, everything else → OpenAI Chat Completions
- Caches the catalog on disk and refreshes on demand
- Sends an `APP-Code` header (defaults to `DBPV7867`) for developer discounts

AI services powered by AIHubMix.

## Install

```bash
pi install npm:@h00w/pi-provider-aihubmix
```

Or for local development:

```bash
pi install ./path/to/pi-provider-aihubmix
# or one-shot
pi -e ./path/to/pi-provider-aihubmix
```

## Setup

1. Create an API key at [console.aihubmix.com](https://console.aihubmix.com) (`sk-...`).
2. Provide the key in either way:

```bash
export AIHUBMIX_API_KEY=sk-...
```

or inside pi:

```text
/login aihubmix
```

3. Pick a model:

```text
/model auto
/model aihubmix/gpt-5.6-sol
/model aihubmix/claude-sonnet-5
```

`/model`, the footer, and `--list-models` primarily show model ids. Use `provider/id` when you need to disambiguate.

> Models only appear in `/model` and `--list-models` after an API key is available
> (env var, `/login aihubmix`, or `--api-key`).
>
> If you install the package but have not configured a key yet, `/model` no longer
> errors with `Could not refresh aihubmix` — log in or export the env var to use models.
>
> Behind an HTTP proxy, this extension reads `HTTP(S)_PROXY` / `NO_PROXY` for catalog
> refresh. Alternatively set `NODE_USE_ENV_PROXY=1` so Node's global fetch uses the proxy.

## What gets registered

By default the extension:

| Rule | Behavior |
|------|----------|
| Type | Only `llm` / chat models from the catalog |
| Tools | Keeps models that advertise `tools` or `function_calling` |
| Auto router | Always includes `auto` (smart router) |
| Pure chat | Excluded when `requireTools` is true |

Protocol routing:

| Model | API | Base URL |
|-------|-----|----------|
| `claude*` | `anthropic-messages` | `https://aihubmix.com` |
| `cc-*`, `anthropic-*` (configurable) | `anthropic-messages` | `https://aihubmix.com` |
| `gemini*` / `gemma*` | `google-generative-ai` | `https://aihubmix.com/gemini/v1beta` |
| everything else | `openai-completions` | `https://aihubmix.com/v1` |

`cc-*` models are AIHubMix Claude Code endpoints and expect the Anthropic Messages wire format. Prefix routing is controlled by `forceAnthropicPrefixes`.

## Configuration

Optional file: `~/.pi/agent/aihubmix.json`

```json
{
  "apiKeyEnv": "AIHUBMIX_API_KEY",
  "baseUrl": "https://aihubmix.com/v1",
  "anthropicBaseUrl": "https://aihubmix.com",
  "geminiBaseUrl": "https://aihubmix.com/gemini/v1beta",
  "appCode": "DBPV7867",
  "includeAuto": true,
  "requireTools": true,
  "allow": [],
  "deny": [],
  "protocols": {
    "openai": true,
    "anthropic": true,
    "gemini": true
  },
  "forceAnthropicPrefixes": ["cc-", "anthropic-"],
  "cacheTtlHours": 12
}
```

### Fields

| Field | Default | Description |
|-------|---------|-------------|
| `apiKeyEnv` | `AIHUBMIX_API_KEY` | Env var holding the API key |
| `baseUrl` | `https://aihubmix.com/v1` | OpenAI-compatible endpoint |
| `anthropicBaseUrl` | `https://aihubmix.com` | Anthropic Messages endpoint |
| `geminiBaseUrl` | `https://aihubmix.com/gemini/v1beta` | Gemini native endpoint (must include `/v1beta` for pi) |
| `appCode` | `DBPV7867` | Value for the `APP-Code` header. Set `""` to disable |
| `includeAuto` | `true` | Keep smart-router `auto` models |
| `requireTools` | `true` | Drop models without tool/function calling |
| `allow` | `[]` | Substring allowlist (empty = all) |
| `deny` | `[]` | Substring denylist |
| `protocols.*` | all `true` | Enable/disable wire protocols |
| `forceAnthropicPrefixes` | `["cc-", "anthropic-"]` | Model id prefixes forced onto Anthropic Messages (`startsWith`, case-insensitive). Use `[]` to disable |
| `cacheTtlHours` | `12` | Disk cache lifetime |

### APP-Code

Requests include:

```http
APP-Code: DBPV7867
```

Override or disable in config:

```json
{ "appCode": "your-code" }
```

```json
{ "appCode": "" }
```

See [AIHubMix APP-Code docs](https://docs.aihubmix.com/en/api/App-code).

## Commands

| Command | Description |
|---------|-------------|
| `/aihubmix-refresh` | Force-refresh the model catalog (bypass cache) |
| `/aihubmix-status` | Show registered model count, source, and config summary |

## Cache

Catalog cache file:

```text
~/.pi/agent/aihubmix-models-cache.json
```

- Fresh cache is reused within `cacheTtlHours` (including native `/model` soft refresh)
- Network failures fall back to a stale cache when available
- Offline / `allowNetwork=false` refresh uses the disk cache only
- Offline first-run falls back to a single `auto` model
- Catalog HTTP goes through `HTTP(S)_PROXY` when set (see Setup note above)

## Conflict with models.json

If `~/.pi/agent/models.json` already defines `providers.aihubmix`, pi layers that file over this extension. You will see a warning on load. Prefer either:

- let this extension manage the catalog, or
- use `modelOverrides` in `models.json` for small tweaks

## Development

```bash
npm install
npm test
npm run typecheck

# try locally
pi -e .
```

## License

MIT