> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> AIHubMix Skill 为 Codex、Claude Code、Cursor、Cline 等 AI Agent 提供实时模型查询、接入配置、调用示例生成与错误排查能力。

**AIHubMix Skill** 是面向 AI 编程助手的一套本地扩展能力。安装后，你可以在 Codex、Claude Code、Cursor、Cline 等支持 Skills 的 Agent 里，用自然语言完成 AIHubMix 接入、模型查询、能力选型、示例生成和错误排查。

该 Skill 不内置固定模型清单，而是在需要时从 AIHubMix 官方接口读取模型、价格、上下文、协议契约等实时信息，让 Agent 避免依赖过期记忆。

## 适用场景

| 场景          | 你可以这样说                         | Skill 会做什么                            |
| ----------- | ------------------------------ | ------------------------------------- |
| 接入 AIHubMix | “把这个项目接入 AIHubMix”             | 识别项目技术栈，选择合适协议，给出最小可运行接入方式            |
| 查询模型        | “查一下 gemini 最新可用模型”            | 从 AIHubMix 实时模型接口查询并整理结果              |
| 按能力选型       | “有哪些可用的图片输入模型？”                | 按视觉、文生图、视频、TTS、STT、向量、重排等能力筛选候选模型     |
| 生成示例        | “给我一个 Anthropic messages 调用示例” | 生成 OpenAI、Anthropic、Gemini 等协议下的可运行示例 |
| 校验 Key      | “帮我确认这个模型能不能用”                 | 通过真实最小调用校验 API Key 与模型可调用性            |
| 排查错误        | “这个 401 / 400 是什么原因？”          | 结合接口、模型、错误体和请求 ID 分析处理方式              |

## 前置条件

* 至少安装一个支持 Skills 的 AI Agent，例如 Codex、Claude Code、Cursor、Cline、Gemini CLI、OpenCode 等。
* 本机可运行 Python 3.8 或更高版本。
* 如需真实调用模型，需要准备 [AIHubMix API Key](https://console.aihubmix.com/token)。
* 如需查询余额、Key 列表或当前账号可调用模型，需要额外安装并登录官方 `aihubmix` CLI。

## 安装

### 方式一：让 Agent 帮你安装

把下面这段话交给当前使用的 AI Agent：

```text theme={null}
请安装 AIHubMix Skill：从 https://github.com/AIhubmix/skills 获取，放入当前工具的 Skills 目录。

Claude Code 可使用 ~/.claude/skills，
Codex 可使用 ~/.codex/skills。

安装后运行 python <skill>/scripts/AiHubMixAPI.py --help 验证。
```

### 方式二：手动安装

```bash theme={null}
# Claude Code
cp -r AiHubMixAPI ~/.claude/skills/

# Codex
cp -r AiHubMixAPI ~/.codex/skills/
```

<Tip>
  不同 Agent 的 Skills 目录可能不同。如果你的工具使用统一目录，可优先查看该 Agent 的 Skills 文档，或让 Agent 自动判断安装位置。
</Tip>

## 可选：安装 AIHubMix CLI

`AiHubMixAPI` 脚本可以读取公开模型和协议信息；账户余额、Key 管理、当前账号实际可调用模型等数据需要官方 CLI 登录后查询。

```powershell theme={null}
# Windows
irm https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.ps1 | iex
```

```bash theme={null}
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/AIhubmix/platfrom-cli/main/install.sh | sh
```

安装后执行：

```bash theme={null}
aihubmix login
aihubmix whoami
aihubmix models list
```

## 如何使用

安装完成后，通常不需要记命令。直接在 Agent 里描述任务即可：

```text theme={null}
把这个 Next.js 项目接入 AIHubMix，用一个可调用的文本模型做 smoke test。

查一下 Claude 系列在 AIHubMix 里的最新模型和价格。

我可以用哪些文生图模型？只看我当前账号能调用的。

这个接口返回 401，帮我判断是 Key、Base URL 还是模型权限问题。
```

如果 Agent 没有自动触发，可以显式调用对应 Skill，例如：

```text theme={null}
/AiHubMixAPI 查询 gemini 最新模型
/AiHubMixAPI 排查这个 400 报错
```

## 命令行用法

进入 Skill 目录后，也可以直接调用脚本：

```bash theme={null}
# 查询模型
python scripts/AiHubMixAPI.py list --limit 20
python scripts/AiHubMixAPI.py report gemini
python scripts/AiHubMixAPI.py compare <model-a> <model-b>

# 按能力查候选模型
python scripts/AiHubMixAPI.py candidates --capability vision
python scripts/AiHubMixAPI.py candidates --capability image-gen
python scripts/AiHubMixAPI.py candidates --capability rerank

# 只看当前账号可调用的候选模型，需要已登录 aihubmix CLI
python scripts/AiHubMixAPI.py candidates --capability vision --mine

```

中文输出可以追加 `--lang zh`，或设置：

```bash theme={null}
export AIHUBMIX_LANG=zh
```

## 能力速查

| 能力                | 推荐命令                                                                |
| ----------------- | ------------------------------------------------------------------- |
| 查看模型列表            | `list`                                                              |
| 查询某个模型或系列         | `get <model-id>` / `report <query>`                                 |
| 对比多个模型            | `compare <model-a> <model-b> ...`                                   |
| 按能力选型             | `candidates --capability <capability>`                              |
| 只看账号可调用模型         | `candidates --capability <capability> --mine`                       |
| 校验 API Key        | `doctor --model <model-id>`                                         |
| 校验图片输入            | `doctor --model <model-id> --image`                                 |
| 生成 OpenAI 兼容示例    | `example chat --model <model-id>`                                   |
| 生成 Anthropic 兼容示例 | `example messages --model <model-id>`                               |
| 排查错误              | `troubleshoot --status <code> --endpoint <path> --model <model-id>` |

## 常见问题

### 安装后 Agent 没有自动调用

不同 Agent 对 Skill 触发的策略不同。可以先直接输入 `/AiHubMixAPI` 显式调用；也可以把需求说得更明确，例如包含“AIHubMix”“模型”“Base URL”“API Key”“报错码”等关键词。

### 公开模型列表里有模型，但我的 Key 调不通

公开模型列表只说明平台存在该模型，不代表当前账号一定有权限或余额可调用。需要使用 `aihubmix models list` 或 `candidates --mine` 查看当前账号实际可调用范围，再用 `doctor --model <model-id>` 做真实校验。

### 什么时候需要安装 `aihubmix` CLI

只查公开资料时不需要。需要余额、Key 管理、账号可调用模型、`--mine` 筛选等账户相关能力时，需要安装并登录 CLI。

### 会不会泄露 API Key

Skill 的脚本会对密钥做脱敏处理。仍然建议不要把真实 Key 写入仓库文件、Issue、PR 描述或聊天记录中；本地调试时使用环境变量传入即可。

## 相关资源

* Skill 仓库：[https://github.com/AIhubmix/skills](https://github.com/AIhubmix/skills)
* AIHubMix CLI：[https://github.com/AIhubmix/platfrom-cli](https://github.com/AIhubmix/platfrom-cli)
* AIHubMix 模型广场：[https://aihubmix.com/models](https://aihubmix.com/models)