# 艾波开放平台 · 接口索引

> Base URL：`https://ai.aibobos.com/api/openapi/v1`　|　更新于 2026-09-26　|　人看的文档中心：https://ai.aibobos.com/openapi/

艾波（AI 工作台）对外开放能力。**任何 OpenAI 客户端 / Agent 用「Base URL + API Key」即可接入**，无需登录后台。

## 端点一览

| # | 方法 | 路径 | 能力域 | 说明 | 文档 |
|---|---|---|---|---|---|
| 1 | `GET` | `/me` | — | 归属与用量 | [me.md](https://ai.aibobos.com/openapi/endpoints/me.md) |
| 2 | `GET` | `/models` | `chat` | 模型列表 | [models.md](https://ai.aibobos.com/openapi/endpoints/models.md) |
| 3 | `POST` | `/chat/completions` | `chat` | 对话（OpenAI 兼容） | [chat-completions.md](https://ai.aibobos.com/openapi/endpoints/chat-completions.md) |
| 4 | `GET` | `/voices` | `tts` | 可用音色 | [voices.md](https://ai.aibobos.com/openapi/endpoints/voices.md) |
| 5 | `POST` | `/tts` | `tts` | 生成配音 | [tts.md](https://ai.aibobos.com/openapi/endpoints/tts.md) |
| 6 | `GET` | `/task?id=<任务ID>` | `tts` | 查询配音任务 | [task.md](https://ai.aibobos.com/openapi/endpoints/task.md) |
| 7 | `GET` | `/records` | `records` | 调用记录 | [records.md](https://ai.aibobos.com/openapi/endpoints/records.md) |

## 鉴权

```
Authorization: Bearer aibo_<40位十六进制>
```

- Key 在后台 **工作台 → 用户 → API Key** 自助签发，**明文只显示一次**。
- 服务端只存 `sha256(明文)`，无法找回，丢了就吊销重签。
- 支持 `expires_at` 过期与「能力域」限权；每账号上限 20 枚。

## 能力域（scope）

| scope | 覆盖 | 端点 |
|---|---|---|
| `chat` | 对话 / 模型列表 | /models、/chat/completions |
| `tts` | 配音（含查询） | /voices、/tts、/task |
| `records` | 调用记录 | /records |
| `draw` | 图像生成（**已预留计费，端点未开放**） | — |

> 签发时默认四项全开。想省额度可只开部分——但注意 `/chat/completions` 的配音意图需要 `tts` 计费配置在位。

## 计费口径

按调用扣算力，与站点原生模块同一套账（会员免费额度、黑名单、余额校验全部生效）。

| module | cost_type | 名称 | 算力/次 |
|---|---|---|---|
| `openapi` | `chat` | 开放对话调用 | 1 |
| `openapi` | `tts` | 开放配音调用 | 1 |
| `openapi` | `draw` | 开放图片调用 | 5（端点未开放） |

**三条硬规则**：

1. **失败即退回**：交付失败走 `XbCore::refund` 原路退回，不吞算力。
2. **不可用不接单**：通道未就绪直接 `503` 且不扣——宁可不接，不做假交付。
3. **成功才计费**：`402` 是扣费失败，此时**没有交付物**，也不会留下扣费记录。

## 错误码

| HTTP | message | 含义 |
|---|---|---|
| `401` | 缺少 Authorization: Bearer <API Key> | 没带 Key 或格式不对。 |
| `401` | API Key 无效或已被删除 | Key 不存在，或已在后台删除。 |
| `401` | API Key 已被吊销 | Key `status=0`，不可恢复，请重新签发。 |
| `401` | API Key 已过期 | 超过 `expires_at`。 |
| `401` | 该 Key 未开通此能力（scope: xxx） | 能力域不含该端点所需 scope。 |
| `400` | text 不能为空 / messages 不能为空 | 参数缺失。 |
| `400` | 文案超出长度限制 | 超过 `tts_max_chars`。 |
| `402` | 算力不足：… | 扣费失败（余额/免费额度/黑名单）。**未产生交付，不计费**。 |
| `404` | 任务不存在 | 任务 ID 不存在或不属于当前账号。 |
| `500` | 生成失败：… | 上游模型异常。**已自动退回本次算力**。 |
| `503` | 配音通道未就绪：… | 语音通道全不可用。**本次不扣算力**，可直接重试。 |

## 给机器读的文件

- [`/llms.txt`](https://ai.aibobos.com/llms.txt) —— Agent 抓取入口
- [`/openapi.json`](https://ai.aibobos.com/openapi.json) —— OpenAPI 3.1 标准描述（可直接导入 Postman / 生成 SDK / 喂给 function-calling）
- [`/openapi/agent-quickstart.md`](https://ai.aibobos.com/openapi/agent-quickstart.md) —— 一页接入说明，可整段塞进 Agent 的 system prompt

## 别做的事

- **不要把 Key 写进前端代码或公开仓库**——服务端不会校验来源，谁拿到谁能用。
- **不要并发轮询 `/task`**——2–3 秒一次足够，高频轮询不会更快。
- **不要假设流式**——`stream=true` 当前按非流式返回。