docs: expand integration guides
This commit is contained in:
1 parent
f5f855c751
commit
4e09dfa0e0
3 files changed
+100
No files matched your search
@@ -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