# @d3ara1n/pi-provider-unisound

[![npm version](https://img.shields.io/npm/v/@d3ara1n/pi-provider-unisound)](https://www.npmjs.com/package/@d3ara1n/pi-provider-unisound) [![npm downloads](https://img.shields.io/npm/dm/@d3ara1n/pi-provider-unisound)](https://www.npmjs.com/package/@d3ara1n/pi-provider-unisound) [![license](https://img.shields.io/npm/l/@d3ara1n/pi-provider-unisound)](https://www.npmjs.com/package/@d3ara1n/pi-provider-unisound)

Unisound (云知声) MaaS provider for [Pi Coding Agent](https://pi.dev) — registers the U2 model family (plus plan-hosted GLM/Kimi) via the platform's OpenAI-compatible API.

## Providers

| Provider ID | Name | Billing | API Key Env |
|---|---|---|---|
| `unisound` | Unisound MaaS | Pay-as-you-go | `$UNISOUND_API_KEY` |
| `unisound-plan` | Unisound MaaS (Token Plan) | Subscription | `$UNISOUND_PLAN_API_KEY` |

Both channels share the endpoint `https://maas-api.unisound.com/v1`. The keys are **not interchangeable**: pay-as-you-go keys come from *Metered & Packs → API Key Management*, Token Plan keys from *Subscription Management*.

> **Token Plan usage restriction**: plan quota may only be used inside coding tools (U2Claw, OpenClaw, OpenCode and equivalents like pi). Using the plan key for non-coding automation or application backends is considered abuse and may get the key blocked.

## Models

The catalog covers the full platform model set — both channels expose the
same models and differ only in billing (permissions live on the API key).
It is **refreshed from the live API** (`GET /v1/models`) when the cached
snapshot is stale — at most once every 4 hours, matching pi's built-in
catalog cadence — so newly published models appear without a plugin
update:

- **Network refresh**: each registration fetches the live catalog with its
  own key during interactive startup when the persisted snapshot is older
  than 4 hours, and replaces the registered model list. `pi update
  --models` forces an immediate refresh.
- **Offline restore**: the last-seen catalog is persisted to
  `~/.pi/agent/models-store.json` and restored on offline startups
  (`PI_OFFLINE=1`).
- **Metadata**: `context_window` / `max_output` come from the live catalog.
  Modalities, thinking behavior and pricing are not exposed by the
  endpoint and fall back to the shipped specs per model id; models new to
  the catalog get conservative family defaults (text-only input, on/off
  thinking).
- **Fallback**: the shipped spec table is used until the first
  successful network refresh (or while the API is unreachable).

### Reasoning families (shipped specs)

| Family | Thinking levels |
|---|---|
| U2 Flash | on/off (`thinking.type`) |
| U2 | always on (cannot disable) |
| U2 Med | off / low / medium / high (`reasoning_effort`) |
| GLM-5.2, DeepSeek V4 family | off / high / max (`reasoning_effort`) |
| GLM-5.3 / 5.3 Flash | off / low / high / max (`reasoning_effort`) |
| Kimi K3 | low / high / max, always on (`reasoning_effort`) |
| others | on/off (`thinking.type`) — levels unverified |

`u2-radimed` (medical imaging) is no longer listed by the live catalog
and was removed (2026-10); it re-registers automatically if it returns.
Pay-as-you-go U2 pricing is in [Pricing](#pricing); every model on the
Token Plan and unpublished-price third-party models cost 0.

## Compatibility

- **Thinking** is on by default on the U2 models: `u2-flash` and `u2-med` can toggle it, `u2` always reasons, and `u2-radimed` never does. `u2-flash` ignores `reasoning_effort` (re-verified live), so only on/off is offered for it.
- **Reasoning effort** applies to `u2-med` and the plan-hosted models: `u2-med` exposes off / low / medium / high, `glm-5.2` exposes off / high / max, and `kimi-k3` is always-on with low / high / max. Gateway alias levels (e.g. `minimal` → `low` on `u2-med`) are hidden.
- **Image input**: `u2-flash` is text-only; `u2-med` and `u2-radimed` accept images.
- **Context overflow** errors match pi's built-in patterns, so auto-compaction works. Declared context windows are conservative, so pi compacts before the gateway rejects an oversized request.
- **Caching**: the API reports cache-hit tokens, which pi shows as cache-read tokens in the cost estimate.
- Tool calls, streaming, and usage reporting follow the standard OpenAI shapes.

## Pricing

pi tracks cost in USD. Unisound lists CNY prices, so `cost` fields are FX-converted estimates (~7.1 CNY/USD) for pi's status-bar display only — not real billing. List prices (input / cache-hit / output, CNY per million tokens): `u2-flash` 1/0.2/2 (limited-time promos such as the Sept–Oct 2026 free month excluded), `u2` 1/0.02/2, `u2-med` 8/2/28, `u2-radimed` 15/4/20. Token Plan models have subscription billing → `cost` 0. Cache-write pricing is not published.

## Installation

```bash
pi install npm:@d3ara1n/pi-provider-unisound
```

Or add to `~/.pi/agent/settings.json`:

```jsonc
{
  "extensions": [
    "/absolute/path/to/pi-extensions/packages/pi-provider-unisound"
  ]
}
```

Set your API key (pay-as-you-go):

```bash
export UNISOUND_API_KEY="sk-..."
```

Or for the Token Plan:

```bash
export UNISOUND_PLAN_API_KEY="sk-..."
```

Or use `/login` in pi to store them in `~/.pi/agent/auth.json`:

```json
{
  "unisound": { "type": "api_key", "key": "sk-..." },
  "unisound-plan": { "type": "api_key", "key": "sk-..." }
}
```

Then switch models with `/model unisound/u2-flash` or `/model unisound-plan/kimi-k3`.

## Getting an API Key

1. Visit the [Unisound MaaS platform](https://maas.unisound.com)
2. Pay-as-you-go: Metered & Packs → API Key Management
3. Token Plan: subscribe on the [Token Plan](https://maas.unisound.com/token-plan) page, then Subscription Management → dedicated API key

Note that model access is scoped per key — a key without permission for a model returns `no model <id> permission`.

## Dependencies

None — this is a standalone provider with no pi-extension dependencies. It uses pi's built-in `openai-completions` streaming.

## Usage Quota Reporting

Not yet implemented — Unisound MaaS does not currently expose a public quota or balance API. Token Plan credits are visible only in the web console (Subscription Management). When one becomes available, quota reporting will be added via `@d3ara1n/pi-usage-block-core`.