From 4e09dfa0e0420fbefee84370b82d636e1b2075bc Mon Sep 17 00:00:00 2001 From: WangLX <519407855@qq.com> Date: Thu, 24 Sep 2026 14:30:20 +0800 Subject: [PATCH] docs: expand integration guides --- docs/17-catalog-and-key-selection.md | 41 ++++++++++++++++++++ prototype/src/styles.css | 3 ++ prototype/src/views/UserConsole.vue | 56 ++++++++++++++++++++++++++++ 3 files changed, 100 insertions(+) diff --git a/docs/17-catalog-and-key-selection.md b/docs/17-catalog-and-key-selection.md index b8a1e72..006d683 100644 --- a/docs/17-catalog-and-key-selection.md +++ b/docs/17-catalog-and-key-selection.md @@ -25,6 +25,47 @@ API Key 权限窗口支持同时勾选多个模型,再选择各自的分组; 4. 外部应用使用用户端显示的统一 Base URL,路径为 `/v1`,聊天接口为 `/v1/chat/completions`,通过 `Authorization: Bearer ` 认证。 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":"","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`:目录合并、无可用分组的模型、多模型授权集合和分页边界,以及既有流式响应测试。 diff --git a/prototype/src/styles.css b/prototype/src/styles.css index 9981df8..40e9247 100644 --- a/prototype/src/styles.css +++ b/prototype/src/styles.css @@ -215,3 +215,6 @@ td strong{font-size:12px} .usage-filter{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.usage-filter .search-input{min-width:260px;flex:1}.usage-filter select{min-width:120px}.button.danger{color:#fff;border-color:#d94b62;background:#d94b62}.button.danger:hover{background:#bd354d}.danger-icon{color:#c43d55}.usage-table th:first-child,.usage-table td:first-child{width:36px}.usage-table input[type=checkbox]{width:15px;height:15px;accent-color:#6351df}.usage-table code{font-size:10px}.usage-detail-list{margin-bottom:18px}.usage-payload{max-height:180px;overflow:auto;margin:6px 0 15px;padding:11px;border:1px solid var(--border);border-radius:8px;color:#344054;font:11px/1.55 "DM Mono",monospace;white-space:pre-wrap;word-break:break-word;background:#f7f8fb}.table-pagination{display:flex;align-items:center;justify-content:space-between;padding:12px 16px;border-top:1px solid var(--border);color:var(--muted);font-size:11px}.table-pagination>div{display:flex;gap:6px}.rotate-90{transform:rotate(90deg)}.rotate--90{transform:rotate(-90deg)} .docs-guide-extra{padding:24px 28px}.docs-guide-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:14px}.docs-guide-grid article{display:flex;gap:12px;min-height:112px;padding:15px;border:1px solid var(--border);border-radius:10px;background:var(--soft)}.docs-guide-grid article>b{display:grid;flex:0 0 30px;width:30px;height:30px;place-items:center;border:1px solid #d8d0fb;border-radius:8px;color:var(--primary);font-family:"DM Mono",monospace;font-size:10px;background:var(--primary-soft)}.docs-guide-grid h4{margin:1px 0 7px;font-size:13px}.docs-guide-grid p{margin:0;color:var(--text-soft);font-size:11px;line-height:1.65}.docs-guide-grid code{padding:2px 4px;border-radius:4px;color:var(--primary);font-family:"DM Mono",monospace;background:var(--primary-soft)} @media(max-width:700px){.docs-guide-extra{padding:20px 16px}.docs-guide-grid{grid-template-columns:1fr}} +.docs-detail-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:14px;margin-top:14px}.docs-detail-card{min-width:0;padding:24px}.docs-detail-card .panel-header{align-items:flex-start;margin-bottom:14px}.docs-detail-card .panel-header h3{margin-top:5px}.docs-detail-card>p.docs-detail-intro{margin:0 0 13px;color:var(--text-soft);font-size:11px;line-height:1.65}.docs-detail-card pre{overflow:auto;margin:10px 0 0;padding:14px;border-radius:9px;color:#dbe2f5;font:11px/1.65 "DM Mono",monospace;background:#151b2d}.docs-detail-card pre+pre{margin-top:9px}.docs-path-card,.docs-detail-grid>.docs-path-card{grid-column:1/-1}.docs-paths{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px;margin-bottom:14px}.docs-paths>div{padding:15px;border:1px solid var(--border);border-radius:9px;background:var(--soft)}.docs-paths strong{display:block;margin-bottom:6px;font-size:12px}.docs-paths p{margin:0;color:var(--text-soft);font-size:11px;line-height:1.65}.docs-step-list{display:flex;flex-direction:column;gap:13px;padding:0;margin:0;list-style:none}.docs-step-list li{display:grid;grid-template-columns:26px 1fr;gap:10px}.docs-step-list li>b{display:grid;width:25px;height:25px;place-items:center;border-radius:7px;color:var(--primary);font:11px "DM Mono",monospace;background:var(--primary-soft)}.docs-step-list strong{display:block;margin:2px 0 4px;font-size:12px}.docs-step-list p{margin:0;color:var(--text-soft);font-size:11px;line-height:1.65}.docs-detail-card code{padding:2px 4px;border-radius:4px;color:var(--primary);font-family:"DM Mono",monospace;background:var(--primary-soft)}.docs-detail-card pre code{padding:0;color:inherit;background:transparent}.docs-detail-warning{margin:13px 0 0;padding:11px 12px;border-left:3px solid #d4a23b;color:#76591d;font-size:11px;line-height:1.65;background:#fff8e8}.docs-reference-table{display:flex;flex-direction:column;border:1px solid var(--border);border-radius:9px;overflow:hidden}.docs-reference-table>div{display:flex;align-items:center;justify-content:space-between;gap:14px;padding:11px 12px;border-bottom:1px solid var(--border)}.docs-reference-table>div:last-child{border-bottom:0}.docs-reference-table>div>code{flex:0 0 auto}.docs-reference-table span{color:var(--text-soft);font-size:10px;text-align:right}.docs-faq{display:flex;flex-direction:column}.docs-faq p{display:flex;flex-direction:column;gap:4px;margin:0;padding:11px 0;border-bottom:1px solid var(--border)}.docs-faq p:last-child{border-bottom:0}.docs-faq strong{font:11px "DM Mono",monospace;color:var(--text)}.docs-faq span{color:var(--text-soft);font-size:11px;line-height:1.55}.docs-detail-card .docs-note{margin-top:14px} +@media(max-width:900px){.docs-detail-grid{grid-template-columns:1fr}.docs-path-card,.docs-detail-grid>.docs-path-card{grid-column:auto}} +@media(max-width:600px){.docs-detail-card{padding:20px 16px}.docs-paths{grid-template-columns:1fr}.docs-reference-table>div{align-items:flex-start;flex-direction:column;gap:5px}.docs-reference-table span{text-align:left}} diff --git a/prototype/src/views/UserConsole.vue b/prototype/src/views/UserConsole.vue index a7b0732..2abbbb4 100644 --- a/prototype/src/views/UserConsole.vue +++ b/prototype/src/views/UserConsole.vue @@ -654,6 +654,62 @@ MOYI_MODEL=<model-id>
02
<
+
+
INTEGRATION PATHS

两种接入方式

A · 接入自己的系统

适合网站、后端服务、工作流和批处理程序。你的服务保存 MOYI API Key,调用统一的 OpenAI 兼容接口。

B · 接入第三方客户端

适合 Cherry Studio、OpenCode 等客户端。把 Base URL、API Key 和调用模型 ID 填入客户端的 OpenAI-compatible 配置。

先在模型广场选择模型厂商,再从详情中选择渠道分组。客户端里的 model 必须填写“调用模型 ID”,不是展示名称,也不是上游中转站的账号名。

+ +
PATH A · APPLICATION

自己的系统调用

  1. 1
    创建并授权 Key

    在 API Keys 创建密钥,同时勾选需要的模型和渠道分组。密钥完整值只显示一次,请保存在服务端环境变量或密钥管理器中。

  2. 2
    复制三个值

    Base URL:{{ platformApiBaseUrl }};API Key:你的用户 Key;Model:模型详情中的调用模型 ID。

  3. 3
    先用 curl 验证
    curl {{ platformApiBaseUrl }}/chat/completions \
    +  -H "Authorization: Bearer $MOYI_API_KEY" \
    +  -H "Content-Type: application/json" \
    +  -d '{"model":"<model-id>","messages":[{"role":"user","content":"你好"}]}'
+ +
SDK EXAMPLES

Node.js 与 Python

MOYI 提供 OpenAI Chat Completions 兼容接口,可使用常见 OpenAI SDK;只需要替换 Base URL、Key 和模型 ID。

// Node.js
+import OpenAI from 'openai'
+const client = new OpenAI({ baseURL: '{{ platformApiBaseUrl }}', apiKey: process.env.MOYI_API_KEY })
+const result = await client.chat.completions.create({
+  model: '<model-id>', messages: [{ role: 'user', content: '你好' }]
+})
# Python
+import os
+from openai import OpenAI
+client = OpenAI(base_url='{{ platformApiBaseUrl }}', api_key=os.environ['MOYI_API_KEY'])
+result = client.chat.completions.create(
+    model='<model-id>', messages=[{'role': 'user', 'content': '你好'}]
+)
+ +
PATH B · CLIENTS

Cherry Studio

  1. 1
    添加自定义 OpenAI 兼容供应商

    在设置中的模型服务商添加自定义服务商,协议选择 OpenAI / OpenAI-compatible。

  2. 2
    填写连接信息

    API URL / Base URL 填用户端显示的 {{ platformApiBaseUrl }};API Key 填 MOYI 用户 Key;模型列表可手动添加。

  3. 3
    添加模型

    模型 ID 填模型广场详情里的调用模型 ID,显示名称可以自定义;保存后发一条短消息测试。

如果客户端自动补充 /v1,不要再重复填写;最终请求地址应为 {{ platformApiBaseUrl }}/chat/completions。

+ +
PATH B · CLIENTS

OpenCode

新版 OpenCode 可用自定义 OpenAI-compatible provider。把下面示例放进项目的 opencode.jsonc,再在终端设置 Key。

{
+  "$schema": "https://opencode.ai/config.json",
+  "providers": {
+    "moyi": {
+      "name": "MOYI",
+      "env": ["MOYI_API_KEY"],
+      "package": "@opencode/ai/providers/openai-compatible",
+      "settings": { "baseURL": "{{ platformApiBaseUrl }}" },
+      "models": {
+        "<model-id>": { "name": "<display-name>" }
+      }
+    }
+  }
+}
# macOS / Linux
+export MOYI_API_KEY="你的用户 API Key"
+# Windows PowerShell
+$env:MOYI_API_KEY="你的用户 API Key"
+# 在 OpenCode 中运行 /models,选择 moyi/<model-id>

不同版本 OpenCode 的配置键可能显示为 provider 或 providers;以你安装版本的配置示例为准,核心是 OpenAI-compatible、Base URL 和模型 ID 三者一致。

+ +
PATH B · CLIENTS

Codex 兼容边界

当前 MOYI 对外提供的是 /v1/chat/completions。能够选择 Chat Completions / OpenAI-compatible 后端的 Codex 类客户端可以按下面方式配置:

# ~/.codex/config.toml(用户级配置)
+openai_base_url = "{{ platformApiBaseUrl }}"
+
+# macOS / Linux
+export OPENAI_API_KEY="你的 MOYI 用户 API Key"
+# Windows PowerShell
+$env:OPENAI_API_KEY="你的 MOYI 用户 API Key"
+# model 使用模型广场中的调用模型 ID

部分新版 Codex 工作流默认调用 /v1/responses、工具调用或专用认证流程,当前 MOYI 尚未承诺兼容这些接口;若客户端不能切换到 Chat Completions,会出现 404 或参数不兼容,应改用 Cherry Studio、OpenCode 的 OpenAI-compatible 模式,或等待平台提供 Responses 兼容接口。

+ +
API REFERENCE

接口、流式和异步任务

GET {{ platformApiBaseUrl }}/models查询当前 Key 已授权的模型
POST {{ platformApiBaseUrl }}/chat/completions同步聊天;传 stream: true 获取 SSE 流式响应
POST {{ platformApiBaseUrl }}/3d/tasks提交 3D 异步任务
POST {{ platformApiBaseUrl }}/video/tasks提交视频异步任务
GET {{ platformApiBaseUrl }}/tasks/<task-id>查询异步任务进度与结果

文本聊天的费用在完整响应后结算;流式连接中断时仍会根据使用记录处理结算。3D、视频模型不能通过聊天接口调用。

+ +
TROUBLESHOOTING

常见问题

401 / INVALID_API_KEY确认使用的是用户端 API Key,前缀和完整值没有多余空格;停用的 Key 需要先重新启用。

403 / MODEL_FORBIDDEN当前 Key 没有授权这个模型或渠道分组;回到 API Keys 编辑权限。

404 / MODEL_NOT_FOUND模型 ID 填错,或管理员已停用模型/分组;重新从模型详情复制调用 ID。

429 / KEY_BUSY 或 MODEL_BUSY分别表示当前 Key 并发已满,或上游分组共享并发已满;等待后重试,不要重复创建 Key。

余额不足 / PROVIDER_NOT_CONFIGURED用户余额、渠道凭据或上游钱包需要管理员检查;不要在客户端暴露供应商密钥。

+
+
{{ selectedModel.vendorName || '未标注厂商' }}{{ selectedModel.type }} · {{ selectedModel.mode }}调用渠道:{{ selectedModel.provider }}

{{ selectedModel.description }}