skills

---
name: apiyi
description: >-
  Call 400+ AI models (GPT, Claude, Gemini, Grok, DeepSeek, Qwen, Kimi, GLM,
  MiniMax, plus image, video, embedding and rerank models) through APIYI's single
  OpenAI-compatible gateway at api.apiyi.com. Use this when the user mentions
  APIYI, API易, api.apiyi.com or an APIYI_API_KEY; wants one API key across
  multiple model vendors; is repointing an OpenAI, Anthropic or Google SDK
  base_url at a relay; or asks about APIYI base URLs, model IDs, token groups
  (分组), pricing, balance (余额), call logs, or gateway error codes.
license: >-
  Proprietary. Reference documentation for the APIYI service, operated by
  APIYI, LLC. Free to read and follow; the service itself requires an account.
compatibility: >-
  Any agent or SDK that can make HTTPS requests. Verified against the official
  OpenAI, Anthropic and Google GenAI SDKs, and against LangChain, the Vercel AI
  SDK, Claude Code, Cline, Cherry Studio and Codex CLI.
metadata:
  vendor: "APIYI, LLC"
  homepage: "https://api.apiyi.com"
  docs: "https://docs.apiyi.com"
  api_key_env: "APIYI_API_KEY"
  openai_base_url: "https://api.apiyi.com/v1"
  anthropic_base_url: "https://api.apiyi.com"
  gemini_base_url: "https://api.apiyi.com"
  gemini_api_version: "v1beta"
  model_list_endpoint: "https://api.apiyi.com/v1/models"
  console_keys: "https://api.apiyi.com/token"
  console_logs: "https://api.apiyi.com/log"
  console_profile: "https://api.apiyi.com/account/profile"
  model_registry: "https://docs.apiyi.com/model-registry.json"
  developer_kit: "https://docs.apiyi.com/developer-kit"
  cli: "npx apiyi@latest"
  source_repo: "github.com/apiyi-com/skills"
  last_reviewed: "2026-09-03"
  openclaw:
    emoji: "🔑"
    primaryEnv: "APIYI_API_KEY"
    requires:
      bins: ["python3"]
---

# APIYI — one key, 400+ models, OpenAI/Anthropic/Google-compatible gateway

APIYI is an AI API gateway. You point an existing SDK's `base_url` at
`api.apiyi.com`, use an APIYI key, and call models from OpenAI, Anthropic,
Google, xAI, DeepSeek, Alibaba, Moonshot, Zhipu, MiniMax and ByteDance through
one account and one balance. No APIYI-specific SDK exists or is needed.

## When to use this skill

Use it when any of these are true:

- The user mentions APIYI, API易, `api.apiyi.com`, or has an `APIYI_API_KEY`.
- The user wants one API key that works across multiple model vendors.
- The user is repointing an OpenAI, Anthropic or Google GenAI SDK at a relay.
- The user asks about APIYI base URLs, model IDs, token groups (分组), balance
  (余额), call logs, billing, or gateway error codes.
- A request through `api.apiyi.com` returned 400/401/404/429/5xx and needs
  diagnosis.

Do **not** use it when the user is calling a vendor's own API directly
(`api.openai.com`, `api.anthropic.com`, `generativelanguage.googleapis.com`)
and has no APIYI key. Nothing here applies to those.

## What APIYI is not

Stating these up front so you do not invent them:

- **No agent self-registration endpoint.** An account is created by a human at
  `https://api.apiyi.com`. There is no API that mints an account or a key for
  an unattended agent. Ask the user for a key.
- **No free auto-routing model.** There is no `auto`, no `auto:free`, no
  zero-cost tier. New accounts do carry a small trial credit, enough for a
  hello-world; beyond that, calls are billed.
- **No cross-vendor fallback fields.** `models`, `route`, `provider` and similar
  routing extensions are not supported. Pick one `model` per request and
  implement fallback in your own code.
- **No fine-tuning, Files API, org management, or billing management APIs.**
- **Not a model host.** APIYI relays to upstream vendors, so upstream content
  policy, rate limits and outages pass straight through.

## Base URL — the single most common integration bug

### Pick the base URL by SDK, not by model

| SDK / wire format | `base_url` | Why |
|---|---|---|
| OpenAI-compatible (OpenAI SDK, LangChain, Vercel AI SDK, most clients) | `https://api.apiyi.com/v1` | The SDK appends `/chat/completions` to whatever you give it, so `/v1` must be present. |
| Anthropic SDK / Claude-native | `https://api.apiyi.com` | The SDK appends `/v1/messages` itself. Adding `/v1` produces `/v1/v1/messages` and a 404. |
| Google GenAI SDK / Gemini-native | `https://api.apiyi.com` with `api_version` set to `v1beta` | The SDK builds `/v1beta/models/...` itself. Using `v1` mismatches the path. |

That reasoning is the durable part. If you remember why each one differs, you
will never have to look up the table again.

Never leave a trailing slash on `base_url` — it produces doubled slashes and a
404.

### Nodes

Same API on every host; pick by network position, not by feature.

| Host | Use for |
|---|---|
| `api.apiyi.com` | Default for everyone, in and outside mainland China. |
| `b.apiyi.com` | Backup / enterprise. |
| `api-cf.apiyi.com` | Cloudflare CDN. **Text only**, hard ceiling around 100 seconds. Never use it for image, video, or long reasoning calls. |

## Authentication

Model calls use a bearer token:

```http
Authorization: Bearer sk-your-apiyi-key
Content-Type: application/json
```

Keys start with `sk-`. Create and manage them at `https://api.apiyi.com/token`.

Read the key from the environment — the convention across APIYI's own examples
is `APIYI_API_KEY`. Never hardcode a key, never commit one.

**A second, different credential exists.** The account APIs (balance, logs,
token management) use a *personal access token* (starts with `nap_`), created at
`https://api.apiyi.com/account/profile` under Account Options -> Personal Access
Tokens. Each token carries only the permissions ticked at creation (balance needs
"Profile: Read", logs need "Usage & personal records: Read"), and can have an
expiry and an IP allowlist. It goes in the `Authorization` header, with or
without a `Bearer` prefix. It cannot call models. Do not confuse the two, and do
not put it in application code. Legacy *system tokens* retire on 2026-11-11
(UTC+8) and then return 401 `ACCESS_TOKEN_LEGACY_RETIRED`.

### Key setup and self-check

Do this before any other call, and do it in this order:

1. Look for the key in the `APIYI_API_KEY` environment variable. If you are
   running inside OpenClaw, the key the user saved lives at
   `skills.entries.apiyi.apiKey` in `~/.openclaw/openclaw.json` and OpenClaw
   injects it as `APIYI_API_KEY` for you (declared via `metadata.openclaw.primaryEnv`).
2. If there is no key, ask the user for one. They copy it from
   `https://api.apiyi.com/token`. Put it in the environment variable; never write
   it into source, config that gets committed, or a chat transcript.
3. Self-check. Any of these three gives the same status enum:

   - CLI, no install needed (Node 18+): `npx apiyi@latest check`
   - If this skill was installed from `github.com/apiyi-com/skills`, the bundled
     script: `python3 scripts/apiyi.py --check` (prints JSON)
   - Plain curl:

     ```bash
     curl -s -o /dev/null -w "%{http_code}" https://api.apiyi.com/v1/models \
       -H "Authorization: Bearer $APIYI_API_KEY"
     ```

| Status | Meaning | What to tell the user |
|---|---|---|
| `ready` | `/v1/models` returned 200 | Key works. Say how many models are visible and ask what to build. |
| `no_key` | No key found in any location | Ask for a key from `https://api.apiyi.com/token`, then re-check. |
| `invalid_key` | 401 or 403 | Key is wrong, disabled, or exhausted. Ask the user to re-copy it from the console. |
| `network_error` | Timeout, DNS failure, or 5xx | Retry once; if it persists, try `b.apiyi.com`. |

A normal `sk-` key **cannot read the balance**, so there is no `no_balance`
status here. A 429 may mean either rate limiting or an empty balance; do not
guess which. Point the user at `https://api.apiyi.com/account/profile` instead.

## Endpoint map

| Path | Method | Wire format |
|---|---|---|
| `/v1/chat/completions` | POST | OpenAI Chat Completions |
| `/v1/responses` | POST | OpenAI Responses |
| `/v1/messages` | POST | Anthropic Messages (base URL is the root domain) |
| `/v1beta/models/{model}:generateContent` | POST | Gemini generateContent |
| `/v1/embeddings` | POST | OpenAI Embeddings |
| `/v1/images/generations` | POST | OpenAI Images |
| `/v1/images/edits` | POST | OpenAI Image edits |
| `/v1/rerank` | POST | Rerank |
| `/v1/models` | GET | List models available to your key |

Video models do **not** use a single unified path. Each vendor family has its
own submit-and-poll paths. Read the model's own documentation page before
integrating video.

## Model IDs — read this before you type a model name

### The naming rule

Model IDs are **case-sensitive** and **dot-versioned**.

The documentation URLs are not the model IDs. Doc page slugs replace dots with
hyphens for URL safety; the actual ID keeps the dots:

| Documentation URL | Actual model ID |
|---|---|
| `/models/qwen3-7-max` | `qwen3.7-max` |
| `/models/glm-5-2` | `glm-5.2` |
| `/models/gpt-5-6-sol` | `gpt-5.6-sol` |
| `/models/gemini-3-6-flash` | `gemini-3.6-flash` |

So it is `gpt-5.4-mini`, **not** `gpt-5-4-mini`. A hyphenated version number is
a different string and will not resolve. Capitalisation matters too —
`MiniMax-M3` is not `minimax-m3`.

### Always confirm the ID at runtime

The catalog changes weekly. Do not hardcode an ID you have not just seen in a
listing.

```bash
curl -s https://api.apiyi.com/v1/models \
  -H "Authorization: Bearer $APIYI_API_KEY" | jq -r '.data[].id'
```

Without a key, use the public model registry. It is generated from the live
pricing data and is the file the documentation site points agents at:

```bash
curl -s https://docs.apiyi.com/model-registry.json | jq -r '.models[].id'
```

Each entry has `id`, `vendor_en`, `category`, `endpoints`, `groups`,
`billing` (`per_token` or `per_call`, USD list prices) and `docs_url`. Check
`schema_version` (currently 1) before parsing; fields are only ever added, never
renamed, within a schema version.

The raw upstream catalog is a

... (truncated)