选型指南

按使用场景选择 V1 开放 API、Skills 或 MCP 接入方式

云擎数智提供多种接入路径，按你的使用场景选择最合适的方式。

一、三种接入方式对比

维度	V1 开放 API	Skills	MCP 服务
路径	`/v1/*`	安装 `yunsell-ai-skills` 技能包	`/mcp`
鉴权	Bearer Token	`YUNSELL_API_KEY` 环境变量	Bearer Token
典型用户	第三方应用、SDK	Claude、Cursor、Codex、OpenClaw 等	支持 MCP 的 Agent
文本对话	✅ 3 条接口	❌	❌
图像生成	✅	✅ 文生图	✅
视频生成	✅ 含 yunsellai	✅ 含 yunsellai 多模态	✅ 标准 + 轮询
视频下载	✅ content	✅ 自动下载	❌（URL）
TTS	✅ 二进制	✅ 保存本地文件	✅（URL）
流式 SSE	✅ 文本类	❌	❌

结论：

需要 SDK 集成、文本接口、yunsellai 多模态、直接下载二进制 → 用 V1 开放 API
需要在 Agent 对话中 生成图/视频/音频 → 用 Skills（安装 yunsell-ai-skills 技能包）
需要 MCP 协议接入（不安装技能包，直接配置 /mcp）→ 用 MCP 服务

二、V1 API 能力选型

文本：三个接口如何选？

接口	适用场景
`POST /v1/chat/completions`	通用对话、工具调用、多模态输入、流式 SSE
`POST /v1/completions`	Legacy 文本补全（prompt → 续写）
`POST /v1/responses`	多轮 Responses、推理、结构化输出、工具调用

大多数新项目优先使用 Chat Completions。

详见文本 API。

视频：两条创建路径如何选？

接口	适用场景
`POST /v1/videos`	标准视频创建（sora 等），JSON 或 multipart
`POST /v1/yunsellai/videos`	多模态视频：`mode` + `assets[]`（首帧、参考图、续写等）

查询与下载统一使用 GET /v1/videos/{task_id} 和 GET /v1/videos/{task_id}/content。

详见视频 API。

音频：推荐调用顺序

GET /v1/audio/voice/{model} — 获取可用音色
POST /v1/audio/speech — 使用 data[].code 作为 voice 参数合成

详见音频 API。

三、Skills / MCP vs REST 能力对照

能力	REST	Skills（yunsell-ai-skills）	MCP Tool	说明
模型列表	✅	✅	`list_models`	—
文生图	✅	✅	`generate_image`	—
图编辑	✅	❌	`edit_image`	仅 REST / MCP
标准视频	✅	✅	`create_video`	Skills 内置轮询与下载
yunsellai 多模态视频	✅	✅	❌	Skills 支持 7 种 mode
音色列表 + TTS	✅	✅	`list_audio_voices` / `text_to_speech`	—
文本对话	✅	❌	❌	Agent 自身或 REST

四、决策流程图

需要集成到自有应用？
  ├─ 是 → V1 开放 API
  └─ 否 → 在 Agent 对话里生成图/视频/音频？
           ├─ 是 → 安装 Skills 技能包（yunsell-ai-skills）
           │      或配置 MCP 服务（/mcp）
           └─ 否 → 根据具体场景选择 V1 API、Skills 或 MCP

五、相关文档

快速开始

5 分钟内完成第一次 API 调用，了解 V1 API、Skills 与 MCP 三种接入方式

术语表

帮助文档中常见概念、字段与错误术语说明