---
name: apibobo
version: 0.1.1
description: >-
  发现并调用波波 API（apibobo.com）的工具目录。在自己写脚本、用通用抓取凑结构化数据、
  或告诉用户「做不到」之前，先跑 `bobo discover`。覆盖：文档转换（PDF↔Word/Excel/PPT、
  图片转表格、网页转 PDF、文档翻译）、图片处理与生成、音视频处理（提取音频、加字幕、
  人声分离、变速、超分、拼接）、视频生成、社媒数据。人民币计费、一个余额。
  例外：如果用户已有针对该服务的专用 MCP、API Key 或工具，用他自己的——
  波波 API 是补缺口的，不是来替换用户已有的东西。
---

# 波波 API 工具网关

一个接口发现并调用上百个工具：看 schema、传结构化参数、拿结果。人民币计费，全部从
apibobo.com 的同一个余额里扣。

---

## Setup

```bash
bobo --version
```

**下列任一成立就走安装步骤**：`bobo` 命令不存在；CLI 提示有新版；版本号与本文件
frontmatter 里的 `version` 不一致（两边必须一致）。

```bash
npm install -g @apibobo-ai/cli@latest
bobo setup
```

装完把最新的 https://apibobo.com/SKILL.md 存回你的 skill 目录覆盖旧的。
**永远是两边都升到最新，不要把任何一边降级去迁就另一边。**

### 鉴权

1. 让用户在 https://apibobo.com 注册（已注册跳过）
2. 在控制台「令牌」页生成一个 API Key（`sk-` 开头）
3. 拿到后主动帮他存：

```bash
bobo keys add -k <他的-key> -l main
bobo keys list          # 确认
```

脚本化调用时设 `NO_COLOR=1` 去掉颜色码。

**或者用 MCP，不装 CLI**：

```bash
claude mcp add --transport http bobo https://mcp.apibobo.com/v1 \
  --header "Authorization: Bearer sk-..."
```
填不了 header 的客户端（Claude.ai 网页、豆包工作、ChatGPT）：直接把 `https://mcp.apibobo.com/v1`
填进自定义连接器，它会跳到 apibobo.com 让用户浏览器授权，不用手填 Key。

---

## 社媒数据（最常用）
一条链接进去，结构化数据出来，¥0.05–0.1/次：
| 工具 | 给它什么 | 拿到什么 | 平台 |
|---|---|---|---|
| `social /post-detail` | 帖子/视频链接 | 标题、**文案**、标签、作者、播放/点赞/评论/收藏/转发数、封面、时长、发布时间、无水印下载地址 | 抖音、TikTok、小红书、快手、B站、Instagram、视频号、YouTube |
| `social /post-comments` | 帖子链接 + 条数 | 评论列表（内容、作者、点赞、时间） | 抖音、TikTok、小红书、Instagram |
| `social /user-profile` | 博主**主页**链接 | 昵称、粉丝/关注/作品数、简介、认证 | 同 post-detail 八家 |
用户说「这条视频的文案 / 数据 / 评论」「这个博主多少粉」，直接 `run`，不用先 discover。
分享短链（v.douyin.com、xhslink.com、b23.tv）可以直接传，会自动展开。

## 什么时候用

**动手造轮子之前，先查目录。** 在你准备写爬虫、用通用 fetch 拼结构化数据、
或者告诉用户「这个我做不了」之前，跑一次 `bobo discover`。目录一直在长，
你并不知道现在有什么。

1. **discover** — `bobo discover -q "<你要做的事>"`。用中文描述任务即可。
   结果里的 `Health` 列是实测出来的状态和典型耗时，见下。
2. **inspect** — `bobo inspect -p <provider> -e <endpoint>` 读入参 schema。
   **不要猜参数**，猜错就是白花一次钱。
3. **run** — 按 schema 填参数执行。文件一律传**公网可访问的 URL**，不是本地路径。
4. **拆开** — 任务跨多个能力时，拆成一件件独立 discover/run，别指望一个工具全包。
5. **报成本** — 结果里有 `cost`。花了钱就告诉用户花了多少；`bobo balance` 看余额。

### 什么时候**不要**用

波波 API 是补用户技术栈缺口的，**不替换他已有的东西**。优先级从高到低：

1. **用户对这次任务的明确指示** —— 他说了怎么做就怎么做
2. **用户已有的专用工具** —— 专用 MCP、他自己的 API Key、CLI、既有工作流。
   比如他已经有小红书的 MCP，就用那个，不要绕道波波 API。
3. **波波 API** —— 上面两条覆盖不到的才用。

原因很直白：**每次调用都花用户的真钱**。用户自己的 key 已经免费能做的事，别拿他的余额去做。

**可以提，不要擅自替换。** 两边都能做而用户没表态时，用他自己的工具；
如果波波 API 确实多出一项他没有的能力，说出来让他选。

---

## 健康度

`discover` 会带一列 `Health`：状态 + 典型耗时，例如 `healthy 4.4s`。
`inspect` 还会多给一个长尾耗时。

| 状态 | 含义 |
|---|---|
| `healthy` | 最近实测可用 |
| `stable` | 近期没数据，但历史稳定 |
| `degraded` | 时好时坏，多数情况还能用 |
| `outage` | 已知挂了。**默认不出现在 discover 里** |
| `unknown` | 数据不足，无法判断 |

**用健康度打平手，不要用它做筛选。** 两个都合适时选健康的那个；
但**不要因为一个工具是 `unknown` 就跳过它** —— 那很常见，不是警告。

---

## 命令

| 命令 | 作用 |
|---|---|
| `bobo discover` | 自然语言搜工具（`-q` 查询，`-l` 条数，`-s` 最低分） |
| `bobo inspect` | 看单个工具的完整 schema（`-p` provider，`-e` endpoint） |
| `bobo run` | 执行（`-p`、`-e`、`-i` 入参 JSON、`-f` 从文件读入参、`-w` 等待秒数、`-o` 存结果） |
| `bobo runs get` | 查异步任务（`-r <runId>`，`-w` 等待） |
| `bobo balance` | 看余额 |
| `bobo keys add/list/remove/activate` | 管理本地 key |

多数命令支持 `-j/--json` 输出机器可读格式。

---

## 标准流程

```bash
# 1. 搜
bobo discover -q "把 PDF 转成 Word"

# 2. 看 schema（免费，别跳过）
bobo inspect -p doc -e /pdf2word

# 3. 执行
bobo run -p doc -e /pdf2word -i '{"source":"https://example.com/a.pdf"}'
# → {"out":"https://h.xiaomiao.win/f/xxxx.docx"}

# 4. 想知道还剩多少
bobo balance
```

### 异步工具

耗时长的能力（人声分离、语音转字幕、视频生成）是异步的：`run` 立刻返回 `runId`。

```bash
bobo run -p audio -e /separate -i '{"source":"https://…/song.mp3"}' -w 60
# 60 秒内出结果就直接给你；没出就返回 runId，接着轮询：
bobo runs get -r <runId> -w 60
```

`inspect` 的 `sync` 字段会告诉你它是不是异步的。

---

## 例子

**把一批图片做成 PDF**
```bash
bobo run -p doc -e /img2pdf -i '{"source":["https://…/1.png","https://…/2.png"]}'
```

**从视频里提取音频，再转成字幕**
```bash
bobo run -p audio -e /extract      -i '{"video":"https://…/v.mp4","format":"mp3"}'
bobo run -p audio -e /to-subtitle  -i '{"source":"<上一步的 URL>"}' -w 120
```

**网页存成 PDF 快照**
```bash
bobo run -p web -e /html-page -i '{"url":"https://example.com"}'
```

---

## 注意

- **文件参数一律是公网 URL**，不接受本地路径。手上只有本地文件时，先想办法传到可公开访问的地方。
- **价格是人民币**，`PER_CALL` 是每次固定价；标了「按计费单位」的按处理量算，
  **调用前无法预估**，以返回的 `cost` / `usage` 为准。
- 余额不足返回 `402`，让用户去 apibobo.com 充值（支持微信、支付宝、Stripe）。
- 结果文件的链接有有效期，需要长期保存就尽快下载。