# Agent 快速接入（一页版）

> 更新于 2026-09-26　|　把整页丢进 Agent 的 system prompt 就能用。

## 1. 拿到 Key

登录 https://ai.aibobos.com/workbench/ → 用户 → API Key → 签发。明文只显示一次，存到本机凭据文件，别提交到仓库。

## 2. 三个变量

```
AIBO_BASE=https://ai.aibobos.com/api/openapi/v1
AIBO_KEY=aibo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AIBO_AUTH=Authorization: Bearer $AIBO_KEY
```

## 3. 自检（先跑这条）

```bash
curl -s "$AIBO_BASE/me" -H "$AIBO_AUTH"
```
返回 `ok:1` 且 `scopes` 含你需要的域，才继续。

## 4. 两个最有用的调用

**对话**（OpenAI 兼容，任何 SDK 直接指过来）：

```bash
curl -s -X POST "$AIBO_BASE/chat/completions" \
  -H "$AIBO_AUTH" -H "Content-Type: application/json" \
  -d '{"model":"aibo-chat","messages":[{"role":"user","content":"你好"}]}'
```

**配音**（同步优先，通道不可用会转异步）：

```bash
curl -s -X POST "$AIBO_BASE/tts" \
  -H "$AIBO_AUTH" -H "Content-Type: application/json" \
  -d '{"text":"要合成的话","voice_id":""}'
```
返回 `mode:"sync"` 直接用 `audio_url`；返回 `mode:"async"` 就每 3 秒查一次 `/task?id=<id>`，直到 `status=2` 取 `audio_url`。

## 5. 出错怎么办

| 看到 | 动作 |
|---|---|
| `401` | Key 不对/被吊销/过期/缺能力域 → 让用户去后台重签，不要重试 |
| `402` | 算力不足 → 让用户充值，不要重试 |
| `503` | 配音通道未就绪（**没扣费**）→ 可稍后重试 |
| `500` | 上游异常（**已退回算力**）→ 可重试一次 |

## 6. 四条硬约束

1. Key 只在服务端/本机凭据文件，不进前端、不进公开仓库。
2. `/task` 轮询 2–3 秒一次，别并发。
3. 当前不支持流式，别传 `stream=true` 期待 SSE。
4. 音频落在站点 `/uploads/`，要长期留存请自行转存。