AI 开发者套件

账号和 Key 仍需你本人在控制台创建。从「拿到 Key」到「代码跑通」这一段，下面三条路都可以交给 AI。

先选路

Skills · 聊天 Agent

OpenClaw、Claude Code 这类带技能系统的 Agent。装一次技能包，之后用自然语言调用 API易。

CLI · 终端

不写代码，在终端里验证 Key、列模型、发消息、出图。npx apiyi@latest check 零安装。

开发者套件 · 编程 Agent

Cursor、Claude Code、Codex 写接入代码前，先读契约和模型注册表，不编造端点。

套件里有什么

全部是公开地址，不需要登录，任何 Agent 都能直接抓取：

文件	地址	角色
接入契约	`https://docs.apiyi.com/skill.md`	端点表、认证、模型命名规则、常见坑、自检状态、检查单。既是编程 Agent 的规则书，也是 Skills 的正文
模型注册表	`https://docs.apiyi.com/model-registry.json`	模型 ID、可用端点、分组、计费方式与标价的机器可读事实来源，随价格总表自动更新
页面索引	`https://docs.apiyi.com/llms.txt`	全站目录，让 Agent 自己决定该读哪一页
全文合集	`https://docs.apiyi.com/llms-full.txt`	所有页面正文拼接，体积大，按需取用
单页纯文本	任意页面地址后加 `.md`	只关心某一页时，比抓 HTML 省 token
MCP 服务	`https://docs.apiyi.com/mcp`	把本站接成 MCP server，Agent 可随时检索最新内容

本页的纯文本版就是 https://docs.apiyi.com/developer-kit.md。

给编程 Agent 的规则

编程 Agent 最常犯的错不是写不出代码，而是凭记忆编：编一个不存在的端点、把 gpt-5.4-mini 写成 gpt-5-4-mini、给 Anthropic SDK 的 base_url 多加一个 /v1。这五条规则把这些坑挡在前面：

不要编造端点、参数名、枚举值或响应结构。只用 skill.md 端点表里列出的路径；参数以对应协议（OpenAI / Anthropic / Gemini）的官方定义为准。
模型 ID 以 model-registry.json 为唯一事实来源。ID 带点号且区分大小写，文档页地址里的连字符是 URL 安全替换，不是模型 ID。
Base URL 按 SDK 选，不按模型选。OpenAI SDK 用 https://api.apiyi.com/v1；Anthropic SDK 用根域名 https://api.apiyi.com；Google GenAI SDK 用根域名并把 api_version 设为 v1beta。
Key 只从环境变量 APIYI_API_KEY 读。不硬编码、不提交进 git、不贴进对话。
读完先解释，再动手。让 Agent 先说清楚打哪个端点、用哪个模型、超时设多少，你确认后它再改代码。

给 Cursor、Claude Code、Codex 等编程 Agent 的完整版提示词。复制后直接粘贴。

这段提示词替你挡掉了什么

要求	挡掉的坑
不编造端点	Agent 从训练记忆里拼出 `/v1/complete`、`/v1/generate` 这类不存在的路径，然后在 404 里打转
模型 ID 查注册表	`gpt-5-4-mini`、`minimax-m3` 这种连字符或大小写错误会直接 404，且报错信息不会告诉你差在哪
Base URL 按 SDK 选	Anthropic SDK 多加 `/v1` 会拼成 `/v1/v1/messages`；OpenAI SDK 少了 `/v1` 同样 404
Key 只读环境变量	写死在代码里的 Key 会随仓库泄漏；本站 pre-commit 钩子也会拦
先解释再动手	避免 Agent 一上来改十个文件，最后发现选错了协议

Skills 技能包

技能包就是 skill.md 本身：一份专门写给 AI 读的接入说明，装进 Agent 之后，它在需要调用 API易时会自动想起这些规则。三种安装方式：

npx skills（通用）
OpenClaw
手动复制

适用于 Claude Code、Cursor、Codex 等支持 Agent Skills 规范的工具：

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

通过本站的 /.well-known/agent-skills/index.json 自动发现，装的是 skill.md 本体，不带脚本。自检用 npx apiyi@latest check。

OpenClaw 的技能安装器认 git 源，仓库根目录必须有 SKILL.md。本技能的仓库 github.com/apiyi-com/skills 就是这样布局的，还附带自检脚本：

openclaw skills install git:apiyi-com/skills

或者手动克隆到工作区：

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

装好后 Agent 会跑 scripts/apiyi.py --check，按结果引导你配置 Key。

任何能读文件的 Agent 都行。把 https://docs.apiyi.com/skill.md 的内容放进它的技能目录：

Agent	放到
Claude Code	`.claude/skills/apiyi/SKILL.md`
Codex CLI	`.agents/skills/apiyi/SKILL.md`
Cursor	项目规则文件，或直接作为上下文粘贴
其它	直接把全文作为系统提示词的一部分

给 OpenClaw、Claude Code、Cursor 等支持 Skills 的 Agent。复制后直接粘贴。

Key 怎么给它

首选环境变量 APIYI_API_KEY。技能、CLI、所有文档示例都从这里读。
OpenClaw 会把 Key 存在 ~/.openclaw/openclaw.json 的 skills.entries.apiyi.apiKey，运行时自动注入为 APIYI_API_KEY（技能 frontmatter 里的 primaryEnv 声明的就是这个）。配置文件的写法见 OpenClaw 配置文件详解。
CLI 用 npx apiyi@latest auth set-key 存到 ~/.config/apiyi/config.json，文件权限 0600。

自检状态

技能脚本、CLI、手工 curl 三种自检方式返回同一套状态：

状态	含义	Agent 会怎么做
`ready`	`/v1/models` 返回 200	告诉你能看到多少个模型，问你要做什么
`no_key`	哪里都没找到 Key	引导你去控制台复制 Key，存进环境变量后再检
`invalid_key`	401 或 403	Key 错了、被禁用或已耗尽，让你重新复制
`network_error`	超时、DNS 失败或 5xx	重试一次；仍失败则换 `vip.apiyi.com`（海外）或 `b.apiyi.com`

普通 sk- Key 读不到余额，所以没有 no_balance 这个状态。余额和日志用的是另一套系统令牌，见如何查看调用日志。遇到 429 可能是限流也可能是余额用完，Agent 不应猜，应引导你去控制台看。

CLI 命令行

不写代码也能在终端里跑通第一次调用。Node 18 以上，零安装：

npx apiyi@latest check

给任何能执行终端命令的 Agent，或自己逐行执行。

命令一览

命令	需要	做什么
`apiyi check`	Key 可选	检查 Key 来源、节点连通、`/v1/models` 是否 200，打印延迟与状态；有系统令牌时顺带显示余额
`apiyi models [--grep 关键词]`	Key 可选	有 Key 走 `/v1/models` 列你能用的模型；无 Key 读公开注册表
`apiyi chat "提示词" [-m 模型] [--stream]`	Key	发一条 Chat Completions，打印回复与 token 用量。默认模型 `gpt-5.4-mini`
`apiyi responses "输入" [-m 模型] [--effort low]`	Key	走 Responses 端点，打印 `output_text`
`apiyi image "提示词" -m gpt-image-2 [-o 文件名]`	Key	出图并写到本地文件，超时 360 秒
`apiyi balance`	系统令牌	查余额（按 500000 配额 = 1 美元换算）
`apiyi auth set-key` / `show` / `clear`	无	隐藏输入保存 Key；`show` 打码显示；`clear` 清除

全局参数：--api-key、--node api|vip|b|cf（选节点）、--base-url、--timeout、--json（机器可读输出）。

Key 的查找顺序

--api-key 参数 → 环境变量 APIYI_API_KEY → ~/.config/apiyi/config.json → OpenClaw 的 ~/.openclaw/openclaw.json。装过 OpenClaw 技能的用户不用再配一次。

退出码

脚本和 Agent 靠退出码分支，不用解析文字：

码	含义
0	成功
2	`no_key`
3	`invalid_key`（401 / 403）
4	`network_error`（DNS、超时、重试后仍 5xx）
5	模型不存在（404，通常是 ID 写错）
6	限流或余额不足（429）
7	请求参数错误（400，原样打印 `error.message`）
8	命令行参数错误

源码在 github.com/apiyi-com/cli，npm 包名 apiyi。文档一律写 npx apiyi@latest，因为 npx 会缓存旧版本。

model-registry.json 字段说明

每次刷新价格总表时自动重新生成，与模型价格页同源。顶层字段：

字段	含义
`schema_version`	结构版本，当前为 1。同一版本内只增字段不改名
`generated_at`	生成时间（UTC）
`base_urls`	三种 SDK 各自该填的 base_url，以及 Gemini 的 `api_version`
`nodes`	可用节点域名
`endpoints`	端点名到路径与方法的映射：`chat` / `responses` / `messages` / `gemini` / `images` / `embeddings` / `rerank` / `models`
`groups`	分组名到显示名与倍率
`models[]`	见下表

每个模型条目：

字段	含义
`id`	模型 ID，调用时原样使用，区分大小写
`vendor_en`	厂商英文名
`category`	`text` / `image` / `video` / `embedding` 等能力类型
`endpoints`	这个模型能走的端点名，对应顶层 `endpoints` 的键
`groups`	哪些令牌分组能调用它
`billing.type`	`per_token`（按百万 token）或 `per_call`（按次）
`billing.input_usd_per_m` / `output_usd_per_m` / `cache_read_usd_per_m`	按量模型的美元标价
`billing.per_call_usd`	按次模型的单次美元标价
`billing.tiered`	是否有阶梯价（为 true 时详情看模型页）
`docs_url`	有详情页时给出地址

注册表里的价格是标价，不含充值加赠和分组折扣，实际扣费以控制台为准。分组含义见分组说明。

快速开始

两条路：让 AI 接，或自己动手接。

有没有一键对接功能？

有，但形态是把文档交给 AI，而不是一个按钮。

OpenClaw 接入

开源本地 AI 助手，装上技能包后用自然语言调用 API易。

模型价格总表

注册表的人类可读版本，含厂商分组与阶梯价。

产品基础

基础 API

图片 API（官转）

视频 API（官转）

多模态理解 API

文本生成

音频 API（官转）

检索与安全

先选路

Skills · 聊天 Agent

CLI · 终端

开发者套件 · 编程 Agent

套件里有什么

给编程 Agent 的规则

Skills 技能包

Key 怎么给它

自检状态

CLI 命令行

命令一览

Key 的查找顺序

退出码

model-registry.json 字段说明

相关页面

快速开始

有没有一键对接功能？

OpenClaw 接入

模型价格总表

​先选路

Skills · 聊天 Agent

CLI · 终端

开发者套件 · 编程 Agent

​套件里有什么

​给编程 Agent 的规则

​Skills 技能包

​Key 怎么给它

​自检状态

​CLI 命令行

​命令一览

​Key 的查找顺序

​退出码

​model-registry.json 字段说明

​相关页面

快速开始

有没有一键对接功能？

OpenClaw 接入

模型价格总表

先选路

套件里有什么

给编程 Agent 的规则

Skills 技能包

Key 怎么给它

自检状态

CLI 命令行

命令一览

Key 的查找顺序

退出码

model-registry.json 字段说明

相关页面