docs: expand integration guides
This commit is contained in:
1 parent
f5f855c751
commit
4e09dfa0e0
3 files changed
+100
No files matched your search
@@ -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`:目录合并、无可用分组的模型、多模型授权集合和分页边界,以及既有流式响应测试。
|
||||
|
||||
@@ -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}}
|
||||
@@ -654,6 +654,62 @@ MOYI_MODEL=<model-id></code></pre></div></section><section><b>02</b><div><
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section v-if="view === 'docs'" class="docs-detail-grid">
|
||||
<article class="panel docs-detail-card docs-path-card"><header class="panel-header"><div><span>INTEGRATION PATHS</span><h3>两种接入方式</h3></div></header><div class="docs-paths"><div><strong>A · 接入自己的系统</strong><p>适合网站、后端服务、工作流和批处理程序。你的服务保存 MOYI API Key,调用统一的 OpenAI 兼容接口。</p></div><div><strong>B · 接入第三方客户端</strong><p>适合 Cherry Studio、OpenCode 等客户端。把 Base URL、API Key 和调用模型 ID 填入客户端的 OpenAI-compatible 配置。</p></div></div><div class="docs-note"><Info :size="18" /><p>先在模型广场选择模型厂商,再从详情中选择渠道分组。客户端里的 <code>model</code> 必须填写“调用模型 ID”,不是展示名称,也不是上游中转站的账号名。</p></div></article>
|
||||
|
||||
<article class="panel docs-detail-card"><header class="panel-header"><div><span>PATH A · APPLICATION</span><h3>自己的系统调用</h3></div><button class="text-link" @click="copy(platformApiBaseUrl, 'Base URL', 'docs-detail-base-url')"><Check v-if="copySucceeded('docs-detail-base-url')" :size="14" /><Copy v-else :size="14" />{{ copySucceeded('docs-detail-base-url') ? '已复制' : '复制 Base URL' }}</button></header><ol class="docs-step-list"><li><b>1</b><div><strong>创建并授权 Key</strong><p>在 API Keys 创建密钥,同时勾选需要的模型和渠道分组。密钥完整值只显示一次,请保存在服务端环境变量或密钥管理器中。</p></div></li><li><b>2</b><div><strong>复制三个值</strong><p>Base URL:<code>{{ platformApiBaseUrl }}</code>;API Key:你的用户 Key;Model:模型详情中的调用模型 ID。</p></div></li><li><b>3</b><div><strong>先用 curl 验证</strong><pre><code>curl {{ platformApiBaseUrl }}/chat/completions \
|
||||
-H "Authorization: Bearer $MOYI_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"<model-id>","messages":[{"role":"user","content":"你好"}]}'</code></pre></div></li></ol></article>
|
||||
|
||||
<article class="panel docs-detail-card"><header class="panel-header"><div><span>SDK EXAMPLES</span><h3>Node.js 与 Python</h3></div></header><p class="docs-detail-intro">MOYI 提供 OpenAI Chat Completions 兼容接口,可使用常见 OpenAI SDK;只需要替换 Base URL、Key 和模型 ID。</p><pre><code>// 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: '你好' }]
|
||||
})</code></pre><pre><code># 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': '你好'}]
|
||||
)</code></pre></article>
|
||||
|
||||
<article class="panel docs-detail-card"><header class="panel-header"><div><span>PATH B · CLIENTS</span><h3>Cherry Studio</h3></div></header><ol class="docs-step-list"><li><b>1</b><div><strong>添加自定义 OpenAI 兼容供应商</strong><p>在设置中的模型服务商添加自定义服务商,协议选择 OpenAI / OpenAI-compatible。</p></div></li><li><b>2</b><div><strong>填写连接信息</strong><p>API URL / Base URL 填用户端显示的 <code>{{ platformApiBaseUrl }}</code>;API Key 填 MOYI 用户 Key;模型列表可手动添加。</p></div></li><li><b>3</b><div><strong>添加模型</strong><p>模型 ID 填模型广场详情里的调用模型 ID,显示名称可以自定义;保存后发一条短消息测试。</p></div></li></ol><div class="docs-note"><Info :size="18" /><p>如果客户端自动补充 <code>/v1</code>,不要再重复填写;最终请求地址应为 <code>{{ platformApiBaseUrl }}/chat/completions</code>。</p></div></article>
|
||||
|
||||
<article class="panel docs-detail-card"><header class="panel-header"><div><span>PATH B · CLIENTS</span><h3>OpenCode</h3></div></header><p class="docs-detail-intro">新版 OpenCode 可用自定义 OpenAI-compatible provider。把下面示例放进项目的 <code>opencode.jsonc</code>,再在终端设置 Key。</p><pre><code>{
|
||||
"$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>" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}</code></pre><pre><code># macOS / Linux
|
||||
export MOYI_API_KEY="你的用户 API Key"
|
||||
# Windows PowerShell
|
||||
$env:MOYI_API_KEY="你的用户 API Key"
|
||||
# 在 OpenCode 中运行 /models,选择 moyi/<model-id></code></pre><p class="docs-detail-warning">不同版本 OpenCode 的配置键可能显示为 <code>provider</code> 或 <code>providers</code>;以你安装版本的配置示例为准,核心是 OpenAI-compatible、Base URL 和模型 ID 三者一致。</p></article>
|
||||
|
||||
<article class="panel docs-detail-card"><header class="panel-header"><div><span>PATH B · CLIENTS</span><h3>Codex 兼容边界</h3></div></header><p class="docs-detail-intro">当前 MOYI 对外提供的是 <code>/v1/chat/completions</code>。能够选择 Chat Completions / OpenAI-compatible 后端的 Codex 类客户端可以按下面方式配置:</p><pre><code># ~/.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</code></pre><div class="docs-note"><Info :size="18" /><p>部分新版 Codex 工作流默认调用 <code>/v1/responses</code>、工具调用或专用认证流程,当前 MOYI 尚未承诺兼容这些接口;若客户端不能切换到 Chat Completions,会出现 404 或参数不兼容,应改用 Cherry Studio、OpenCode 的 OpenAI-compatible 模式,或等待平台提供 Responses 兼容接口。</p></div></article>
|
||||
|
||||
<article class="panel docs-detail-card"><header class="panel-header"><div><span>API REFERENCE</span><h3>接口、流式和异步任务</h3></div></header><div class="docs-reference-table"><div><code>GET {{ platformApiBaseUrl }}/models</code><span>查询当前 Key 已授权的模型</span></div><div><code>POST {{ platformApiBaseUrl }}/chat/completions</code><span>同步聊天;传 <code>stream: true</code> 获取 SSE 流式响应</span></div><div><code>POST {{ platformApiBaseUrl }}/3d/tasks</code><span>提交 3D 异步任务</span></div><div><code>POST {{ platformApiBaseUrl }}/video/tasks</code><span>提交视频异步任务</span></div><div><code>GET {{ platformApiBaseUrl }}/tasks/<task-id></code><span>查询异步任务进度与结果</span></div></div><p class="docs-detail-warning">文本聊天的费用在完整响应后结算;流式连接中断时仍会根据使用记录处理结算。3D、视频模型不能通过聊天接口调用。</p></article>
|
||||
|
||||
<article class="panel docs-detail-card"><header class="panel-header"><div><span>TROUBLESHOOTING</span><h3>常见问题</h3></div></header><div class="docs-faq"><p><strong>401 / INVALID_API_KEY</strong><span>确认使用的是用户端 API Key,前缀和完整值没有多余空格;停用的 Key 需要先重新启用。</span></p><p><strong>403 / MODEL_FORBIDDEN</strong><span>当前 Key 没有授权这个模型或渠道分组;回到 API Keys 编辑权限。</span></p><p><strong>404 / MODEL_NOT_FOUND</strong><span>模型 ID 填错,或管理员已停用模型/分组;重新从模型详情复制调用 ID。</span></p><p><strong>429 / KEY_BUSY 或 MODEL_BUSY</strong><span>分别表示当前 Key 并发已满,或上游分组共享并发已满;等待后重试,不要重复创建 Key。</span></p><p><strong>余额不足 / PROVIDER_NOT_CONFIGURED</strong><span>用户余额、渠道凭据或上游钱包需要管理员检查;不要在客户端暴露供应商密钥。</span></p></div></article>
|
||||
</section>
|
||||
|
||||
<SlidePanel v-if="selectedModel" :title="selectedModel.name" eyebrow="MODEL DETAILS" @close="selectedModel = null">
|
||||
<div class="drawer-model-head"><span class="model-icon" :class="selectedModel.accent"><component :is="selectedModel.icon" :size="22" /></span><div><small>{{ selectedModel.vendorName || '未标注厂商' }}</small><strong>{{ selectedModel.type }} · {{ selectedModel.mode }}调用</strong><small>渠道:{{ selectedModel.provider }}</small></div></div>
|
||||
<p class="drawer-description">{{ selectedModel.description }}</p>
|
||||
|
||||
Reference in new issue
Block a user