docs: expand integration guides

This commit is contained in:
wlx committed 2026-09-24 14:30:20 +08:00
1 parent f5f855c751
commit 4e09dfa0e0
3 files changed
+100

No files matched your search

+41
View File
@@ -25,6 +25,47 @@ API Key 权限窗口支持同时勾选多个模型,再选择各自的分组;
4. 外部应用使用用户端显示的统一 Base URL,路径为 `/v1`,聊天接口为 `/v1/chat/completions`,通过 `Authorization: Bearer <API_KEY>` 认证。
5. 使用记录查看模型、厂商、渠道分组、Token、费用、耗时和时间;任务中心查看异步任务进度与结果。余额、权限或并发不足时,按错误提示处理后再重试。
## 两种接入路径
### 路径 A:用户自己的系统接入
1. 在模型广场按模型厂商筛选,打开模型详情,选择已上线的渠道分组并复制“调用模型 ID”。模型厂商是实际研发方,渠道分组是请求经过的中转站或官方接口,两者不是同一个字段。
2. 在 API Keys 创建用户 Key,同时勾选要使用的模型和分组。完整 Key 只在创建后显示一次,必须放在服务端环境变量或密钥管理器中,不能写入浏览器代码、Git 仓库或日志。
3. 使用用户端显示的统一 Base URL。当前聊天接口是 `POST {BASE_URL}/chat/completions`,认证头是 `Authorization: Bearer {MOYI_API_KEY}`,请求体中的 `model` 使用调用模型 ID。
```bash
curl "$MOYI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $MOYI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<model-id>","messages":[{"role":"user","content":"你好"}]}'
```
常见 OpenAI SDK 只需指定 `base_url` / `baseURL` 和 API Key;流式聊天在请求中增加 `stream: true`。调用前可用 `GET {BASE_URL}/models` 检查当前 Key 已授权的模型。3D 和视频模型使用 `/3d/tasks`、`/video/tasks` 提交异步任务,再通过 `/tasks/{id}` 查询结果,不能发送到聊天接口。
### 路径 B:Cherry Studio、OpenCode、Codex 等客户端
这些客户端必须选择 **OpenAI-compatible / Chat Completions** 类型,并填写三项:
| 字段 | 填写内容 |
| --- | --- |
| API URL / Base URL | 用户端显示的统一 Base URL,例如 `https://你的域名/v1` |
| API Key | 用户在 MOYI 创建的 API Key |
| Model | 模型详情中的调用模型 ID |
- **Cherry Studio**:添加自定义 OpenAI 兼容服务商,填 Base URL、Key,手动添加模型 ID。若客户端会自动补 `/v1`,不要重复填写,最终请求应落到 `{BASE_URL}/chat/completions`。
- **OpenCode**:新版可在 `opencode.jsonc` 的 `providers` 中使用 `@opencode/ai/providers/openai-compatible`,设置 `settings.baseURL` 和模型 ID;运行 `/models` 后选择该模型。旧版配置键可能显示为 `provider`,以本地版本示例为准。
- **Codex**:只有能切换到 Chat Completions/OpenAI-compatible 后端的客户端形态可以直接使用 `openai_base_url` 和 `OPENAI_API_KEY`。部分新版 Codex 工作流默认请求 `/v1/responses` 或专用工具接口,当前 MOYI 尚未承诺兼容这些接口;若不能切换协议,会出现 404 或参数错误,应暂时使用 Cherry Studio、OpenCode 的兼容模式。
第三方客户端只保存用户自己的 MOYI Key;中转站账号、上游 API Key 和供应商凭据始终只配置在管理端渠道,不能发给用户。
## 接入前检查清单
- 模型详情存在至少一个“已启用”的渠道分组,并且分组有上游模型 ID、渠道凭据和人民币价格。
- API Key 已授权目标模型和目标分组,Key 状态为正常;不需要为每个客户端重新创建 Key,可以复用同一个 Key 或按应用分别创建多个 Key。
- Base URL 只保留平台域名和 `/v1`,不要填完整的 `/chat/completions`;模型 ID 不要使用模型展示名称。
- 先用短文本请求测试,再启用流式;3D/视频先提交异步任务并轮询状态。
- 401 检查 Key,403 检查模型授权,404 检查模型 ID 或接口路径,429 检查 API Key 并发和上游分组共享并发,余额或渠道错误交给管理员检查。
## 验证
- `cd prototype; npm test`:目录合并、无可用分组的模型、多模型授权集合和分页边界,以及既有流式响应测试。