AI Developer Kit

The account and the key still have to be created by you in the console. Everything from “I have a key” to “the code works” can be delegated to an AI through any of the three paths below.

Pick a path

Skills · chat agents

OpenClaw, Claude Code and other agents with a skills system. Install the skill once, then call APIYI in natural language.

CLI · terminal

No code. Verify a key, list models, send a message and generate an image from the terminal. npx apiyi@latest check needs no install.

Developer kit · coding agents

Cursor, Claude Code and Codex read the contract and the model registry before writing integration code. No invented endpoints.

What is in the kit

Every file is public. No login is needed, and any agent can fetch them directly:

File	URL	Role
Integration contract	`https://docs.apiyi.com/skill.md`	Endpoint table, authentication, model-naming rules, known pitfalls, self-check statuses, verification checklist. It is both the rulebook for coding agents and the body of the skill
Model registry	`https://docs.apiyi.com/model-registry.json`	Machine-readable source of truth for model IDs, endpoints, groups, billing type and list prices. Regenerated with the pricing table
Page index	`https://docs.apiyi.com/llms.txt`	Site-wide index so the agent can decide which page to read
Full text	`https://docs.apiyi.com/llms-full.txt`	Every page concatenated. Large; fetch on demand
Single page as text	Append `.md` to any page URL	When you only need one page. Cheaper than HTML
MCP server	`https://docs.apiyi.com/mcp`	Connect this site as an MCP server so the agent can search the latest content

The plain-text version of this page is https://docs.apiyi.com/en/developer-kit.md.

Rules for coding agents

The most common failure of a coding agent is not bad code. It is writing from memory: inventing an endpoint that does not exist, typing gpt-5-4-mini instead of gpt-5.4-mini, or adding an extra /v1 to the Anthropic SDK base URL. Five rules stop that:

Do not invent endpoints, parameter names, enum values or response shapes. Use only the paths in the skill.md endpoint table; parameters follow the official definition of the protocol in use (OpenAI, Anthropic or Gemini).
model-registry.json is the single source of truth for model IDs. IDs are dot-versioned and case-sensitive. The hyphens in documentation URLs are URL-safe replacements, not model IDs.
Pick the base URL by SDK, not by model. The OpenAI SDK uses https://api.apiyi.com/v1; the Anthropic SDK uses the root https://api.apiyi.com; the Google GenAI SDK uses the root with api_version set to v1beta.
Read the key only from the APIYI_API_KEY environment variable. Never hardcode it, commit it or paste it into a chat.
Explain first, then edit. Have the agent state which endpoint, which model and what timeout it intends to use. It edits code only after you confirm.

Full prompt for Cursor, Claude Code, Codex and other coding agents. Copy and paste as is.

What this prompt protects you from

Requirement	Pitfall it blocks
No invented endpoints	The agent assembles `/v1/complete` or `/v1/generate` from training memory and loops on 404s
Model IDs from the registry	`gpt-5-4-mini` or `minimax-m3` return 404, and the error does not say what is wrong
Base URL by SDK	An extra `/v1` on the Anthropic SDK becomes `/v1/v1/messages`; a missing `/v1` on the OpenAI SDK also 404s
Key only from env	A hardcoded key leaks with the repository; this site’s pre-commit hook blocks it too
Explain before editing	Stops the agent from touching ten files before discovering it picked the wrong protocol

Skills

The skill is skill.md itself: an integration reference written for machines. Once installed, the agent recalls these rules whenever it needs to call APIYI. Three ways to install it:

npx skills (generic)
OpenClaw
Manual copy

For Claude Code, Cursor, Codex and any other tool that supports the Agent Skills spec:

npx skills add https://docs.apiyi.com

Discovery goes through this site’s /.well-known/agent-skills/index.json. This installs skill.md itself without scripts; use npx apiyi@latest check for the self-check.

OpenClaw’s skill installer accepts git sources and expects SKILL.md at the repository root. The skill repository github.com/apiyi-com/skills is laid out that way and ships a self-check script:

openclaw skills install git:apiyi-com/skills

Or clone it into the workspace by hand:

git clone https://github.com/apiyi-com/skills ~/.openclaw/workspace/skills/apiyi

After installing, the agent runs scripts/apiyi.py --check and guides you through key setup based on the result.

Works with any agent that can read files. Put the contents of https://docs.apiyi.com/skill.md into its skills directory:

Agent	Location
Claude Code	`.claude/skills/apiyi/SKILL.md`
Codex CLI	`.agents/skills/apiyi/SKILL.md`
Cursor	A project rules file, or paste it as context
Others	Include the full text in the system prompt

For OpenClaw, Claude Code, Cursor and other agents that support skills. Copy and paste as is.

How the key reaches the agent

The environment variable APIYI_API_KEY comes first. The skill, the CLI and every example in these docs read it from there.
OpenClaw stores the key at skills.entries.apiyi.apiKey in ~/.openclaw/openclaw.json and injects it as APIYI_API_KEY at run time. That is what the primaryEnv field in the skill frontmatter declares. See OpenClaw configuration file for the file layout.
The CLI saves it with npx apiyi@latest auth set-key to ~/.config/apiyi/config.json with mode 0600.

Self-check statuses

The skill script, the CLI and a manual curl all return the same status set:

Status	Meaning	What the agent does
`ready`	`/v1/models` returned 200	Tells you how many models are visible and asks what to build
`no_key`	No key found anywhere	Guides you to copy a key from the console, then re-checks
`invalid_key`	401 or 403	Key is wrong, disabled or exhausted. Asks you to copy it again
`network_error`	Timeout, DNS failure or 5xx	Retries once, then suggests `vip.apiyi.com` (outside mainland China) or `b.apiyi.com`

A normal sk- key cannot read the balance, so there is no no_balance status. Balance and logs use a separate system token, see How to view call logs. A 429 can mean either rate limiting or an empty balance. The agent should not guess; it should point you to the console.

CLI

Get the first call working from the terminal without writing code. Node 18 or newer, nothing to install:

npx apiyi@latest check

For any agent that can run terminal commands, or run the lines yourself.

Commands

Command	Needs	What it does
`apiyi check`	key optional	Reports where the key came from, node reachability, whether `/v1/models` returns 200, latency and status. Shows balance if a system token is configured
`apiyi models [--grep text]`	key optional	With a key, lists the models your key can reach via `/v1/models`; without one, reads the public registry
`apiyi chat "prompt" [-m model] [--stream]`	key	Sends one Chat Completions request and prints the reply and token usage. Default model `gpt-5.4-mini`
`apiyi responses "input" [-m model] [--effort low]`	key	Uses the Responses endpoint and prints `output_text`
`apiyi image "prompt" -m gpt-image-2 [-o file]`	key	Generates an image and writes it to a local file, 360 s timeout
`apiyi balance`	system token	Shows the balance (500000 quota units = 1 USD)
`apiyi auth set-key` / `show` / `clear`	none	Saves the key with hidden input; `show` masks it; `clear` removes it

Global flags: --api-key, --node api|vip|b|cf (pick a node), --base-url, --timeout, --json (machine-readable output).

Key lookup order

--api-key flag, then the APIYI_API_KEY environment variable, then ~/.config/apiyi/config.json, then OpenClaw’s ~/.openclaw/openclaw.json. If you already installed the OpenClaw skill, the CLI reuses that key.

Exit codes

Scripts and agents branch on the exit code instead of parsing text:

Code	Meaning
0	Success
2	`no_key`
3	`invalid_key` (401 / 403)
4	`network_error` (DNS, timeout, or 5xx after retry)
5	Model not found (404, usually a misspelled ID)
6	Rate limited or out of balance (429)
7	Bad request (400, prints `error.message` verbatim)
8	Bad command-line arguments

Source is at github.com/apiyi-com/cli; the npm package is apiyi. The docs always write npx apiyi@latest because npx caches old versions.

model-registry.json fields

Regenerated every time the pricing table is refreshed, from the same data as the model pricing page. Top-level fields:

Field	Meaning
`schema_version`	Schema version, currently 1. Within a version, fields are only added, never renamed
`generated_at`	Generation time (UTC)
`base_urls`	The base URL for each of the three SDKs, plus the Gemini `api_version`
`nodes`	Available node hostnames
`endpoints`	Endpoint name to path and method: `chat` / `responses` / `messages` / `gemini` / `images` / `embeddings` / `rerank` / `models`
`groups`	Group name to display label and ratio
`models[]`	See below

Each model entry:

Field	Meaning
`id`	Model ID, used verbatim in requests, case-sensitive
`vendor_en`	Vendor name in English
`category`	Capability type such as `text`, `image`, `video`, `embedding`
`endpoints`	Endpoint names this model accepts, matching the keys of the top-level `endpoints`
`groups`	Token groups that can call it
`billing.type`	`per_token` (per million tokens) or `per_call`
`billing.input_usd_per_m` / `output_usd_per_m` / `cache_read_usd_per_m`	USD list prices for per-token models
`billing.per_call_usd`	USD list price per call for per-call models
`billing.tiered`	Whether tiered pricing applies (see the model page when true)
`docs_url`	Detail page URL when one exists

Prices in the registry are list prices. They exclude recharge bonuses and group discounts; actual charges follow the console. Groups are explained in Groups explained.

Getting started

Two paths: let an AI integrate, or do it yourself.

Is there one-click integration?

Yes, in the form of handing the docs to an AI rather than a button.

OpenClaw

Open-source local AI assistant; with the skill installed it calls APIYI in natural language.

Model pricing

The human-readable version of the registry, grouped by vendor with tiered prices.

Basics

Basic API

Image API (Official)

Video API (Official)

Multimodal Understanding API

Text Generation

Audio API (Official)

Retrieval & Safety

Pick a path

Skills · chat agents

CLI · terminal

Developer kit · coding agents

What is in the kit

Rules for coding agents

Skills

How the key reaches the agent

Self-check statuses

CLI

Commands

Key lookup order

Exit codes

model-registry.json fields

Getting started

Is there one-click integration?

OpenClaw

Model pricing

​Pick a path

Skills · chat agents

CLI · terminal

Developer kit · coding agents

​What is in the kit

​Rules for coding agents

​Skills

​How the key reaches the agent

​Self-check statuses

​CLI

​Commands

​Key lookup order

​Exit codes

​model-registry.json fields

​Related pages

Getting started

Is there one-click integration?

OpenClaw

Model pricing

Pick a path

What is in the kit

Rules for coding agents

Skills

How the key reaches the agent

Self-check statuses

CLI

Commands

Key lookup order

Exit codes

model-registry.json fields

Related pages