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

+3
View File
@@ -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}}
+56
View File
@@ -654,6 +654,62 @@ MOYI_MODEL=&lt;model-id&gt;</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":"&lt;model-id&gt;","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: '&lt;model-id&gt;', 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='&lt;model-id&gt;', 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": {
"&lt;model-id&gt;": { "name": "&lt;display-name&gt;" }
}
}
}
}</code></pre><pre><code># macOS / Linux
export MOYI_API_KEY="你的用户 API Key"
# Windows PowerShell
$env:MOYI_API_KEY="你的用户 API Key"
# 在 OpenCode 中运行 /models,选择 moyi/&lt;model-id&gt;</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/&lt;task-id&gt;</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>