给谁用
客户自己的后端来接
接口留在客户后端。前端只调自己的业务接口。
服务对象
- 研发团队把剪辑嵌进自己的产品
- 内容平台已有视频、文案和素材
- 分步上线先跑通一种，再加另外三种
使用场景
- 真人口播视频、文案、配音
- 素材混剪文案加多段素材
- 新闻混剪文案加新闻素材
- 视频包装成片加字幕和特效
解决的问题
- 用对接口scene 和合成接口成对
- 先看模板再按详情传素材
- 结果只存一次模板、音色不必每次重做
流程
一条片子怎么走完
先选定模式。光点只走这一条真正要经过的站，停住时下面写这一步交给哪个接口。换一种模式，路径会整条换掉。
四种模式
先看最终接口和 scene
真人口播和视频包装共用 realman_broadcast，也共用 scene=realMan，差别在输入：一个要文案、视频和音色，一个只要已有成片和包装素材。
模板
各模式现成模板
先看封面，就知道这条模板的字幕和版式。点开封面播放样片，和剪辑演示是同一套。样片下方给出模板 id，合成时作为 styleId。列表缓存在本站，打开页面不再请求模板接口。
真人口播只用 scene=realMan。选中的模板 id 就是合成时的 styleId。
01 · scene=realMan
真人口播
真人视频 + 文案 + 配音 + 素材包装。最终接口是 realman_broadcast。
-
1
获取口播文案
调用文案接口读取口播文案。客户也可以使用自己系统里已经确认过的文案。
-
2
准备真人视频
客户平台自己保存用户上传的视频地址。不需要每次重新做数字人克隆。
-
3
准备音色
使用客户系统里已有的音色记录，或先走声音克隆再引用。
-
4
选取模板
模板列表只取 scene=realMan。用户点进某个模板后，再拉模板详情，按详情准备素材。
-
5
调用合成
把文案、视频、音色、模板和模板要求的素材一起交给真人口播合成接口。
请在客户自己的业务后端实现「真人口播」。前端只调用客户路由 POST /api/smartclip/realman，不要接触销豹。 先读这些 Markdown，再写代码，字段以文档为准，不要编造： - 模板列表 https://xiaoapis.com/model/smartclip/template.md - 模板详情 https://xiaoapis.com/model/smartclip/template_detail.md - 真人口播合成 https://xiaoapis.com/model/smartclip/realman_broadcast.md - 任务查询 https://xiaoapis.com/model/smartclip/task_query.md 按这个顺序做： 1. 模板列表：POST https://xiaoapis.com/api/smartclip/template ，JSON 里 scene 固定 realMan。列表可以缓存在客户平台。文档 https://xiaoapis.com/model/smartclip/template.md 2. 用户选定模板后：POST https://xiaoapis.com/api/smartclip/template_detail ，JSON 带 id（也兼容 template_id）。按返回图层准备素材。文档 https://xiaoapis.com/model/smartclip/template_detail.md 3. 合成：POST https://xiaoapis.com/api/smartclip/realman_broadcast?action=create ，Content-Type: application/json。必填 key、styleId、videoUrl、callback_url。styleId 用模板 id。videoUrl 是客户已经保存的真人视频公网地址，mp4 或 mov。resolution 只用 720p 或 1080p。title、materials、subtitle、packRules、processRules、structLayers 按文档选填。materials 每项要有 type（image 或 video）和 fileUrl。不要往这个接口传音色 ID。文档 https://xiaoapis.com/model/smartclip/realman_broadcast.md 4. 用返回的 task_id 轮询 GET https://xiaoapis.com/api/smartclip/task_query 。status 为 completed 时取 video_url；failed 时把 error.message 或 fail_reason 交给调用方。提交后约 2 秒开始，间隔 2 到 5 秒。查询不扣费。文档 https://xiaoapis.com/model/smartclip/task_query.md 约束：API Key 只放服务端环境变量；POST JSON 时 key 写在 JSON Body。不要使用 oralMixCutting 或 newsMixCutting 的模板。不要每次重新克隆数字人或音色。videoUrl、素材地址、背景音乐地址不能重名。视频地址无法解析时长时请求会被拒绝。做完给出客户路由、一份请求示例和失败时的返回。
02 · scene=oralMixCutting
素材混剪
口播文案 + 配音 + 多个素材。最终接口是 broadcast_mixcut。
-
1
获取口播文案
同样先拿到口播文案。这一步和真人口播共用文案接口。
-
2
准备音色
用音色接口创建记录，或直接使用客户系统已经保存的音色。
-
3
选取模板
模板列表只取 scene=oralMixCutting。不要拿 realMan 的模板来混剪。
-
4
准备混剪素材
按模板和合成接口的要求准备多段素材。格式、数量、尺寸、时长在上传时就校验。
-
5
调用混剪
把文案、音色、模板和素材交给口播混剪接口。
请在客户自己的业务后端实现「素材混剪」。前端只调用客户路由 POST /api/smartclip/mixcut。 先读这些 Markdown，再写代码，字段以文档为准，不要编造： - 视频文案 https://xiaoapis.com/model/video/text.md - 语音合成 https://xiaoapis.com/model/aihuman/tts.md - 语音合成查询 https://xiaoapis.com/model/aihuman/tts_query.md - 模板列表 https://xiaoapis.com/model/smartclip/template.md - 素材混剪 https://xiaoapis.com/model/smartclip/broadcast_mixcut.md - 任务查询 https://xiaoapis.com/model/smartclip/task_query.md 按这个顺序做： 1. 口播文案：用客户已确认的文案，或 POST https://xiaoapis.com/api/video/text 。content 传视频或音频公网 URL；不带 taskId 是提交，带 taskId 是查询，结果在 resultText。文档 https://xiaoapis.com/model/video/text.md 2. 配音：用已保存的 voice_id 调 POST https://xiaoapis.com/api/aihuman/tts ，文本不超过 2000 字。voice_type 为 custom（克隆音色）或 public（系统音色）。克隆音色的 lang 只用 zh-cn 或 en。volume、speed 取值 0 到 2，默认 1。用返回的 task_id 调 GET https://xiaoapis.com/api/aihuman/tts_query ，拿到 audio_url。文档 https://xiaoapis.com/model/aihuman/tts.md 和 https://xiaoapis.com/model/aihuman/tts_query.md 3. 模板：POST https://xiaoapis.com/api/smartclip/template ，scene 固定 oralMixCutting。不要拿 realMan 的模板来混剪。文档 https://xiaoapis.com/model/smartclip/template.md 4. 合成：POST https://xiaoapis.com/api/smartclip/broadcast_mixcut?action=create 。必填 key、styleId、materials（至少 1 条）、callback_url。口播声音放 audioUrl，格式 mp3、wav 或 m4a，短于 5 分钟。不要传 content 和 speakerId，当前平台不支持这条分支，会返回 unsupported_speaker_branch。文档 https://xiaoapis.com/model/smartclip/broadcast_mixcut.md 5. 轮询 GET https://xiaoapis.com/api/smartclip/task_query ，completed 取 video_url。查询不扣费。文档 https://xiaoapis.com/model/smartclip/task_query.md 约束：API Key 只放服务端；POST JSON 时 key 写在 JSON Body。素材 URL 必须公网可访问，且彼此不能重名。这个模式不需要真人视频。
03 · scene=newsMixCutting
新闻混剪
新闻文案 + 新闻素材。最终接口是 news_mixcut。
-
1
获取新闻文案
用文案接口读取新闻或资讯文案。本模式不依赖音色和真人视频。
-
2
选取模板
模板列表只取 scene=newsMixCutting。
-
3
准备新闻素材
素材由客户平台上传并管理，规格以模板和合成接口为准。
-
4
调用新闻混剪
把新闻文案、模板和新闻素材交给新闻混剪接口。
请在客户自己的业务后端实现「新闻混剪」。前端只调用客户路由 POST /api/smartclip/news。这个模式不要音色，也不要真人视频。 先读这些 Markdown，再写代码，字段以文档为准，不要编造： - 视频文案 https://xiaoapis.com/model/video/text.md - 模板列表 https://xiaoapis.com/model/smartclip/template.md - 新闻混剪 https://xiaoapis.com/model/smartclip/news_mixcut.md - 任务查询 https://xiaoapis.com/model/smartclip/task_query.md 按这个顺序做： 1. 新闻文案：用客户已有标题，或先 POST https://xiaoapis.com/api/video/text 抽出文案，用户确认后再用。文档 https://xiaoapis.com/model/video/text.md 2. 模板：POST https://xiaoapis.com/api/smartclip/template ，scene 固定 newsMixCutting。文档 https://xiaoapis.com/model/smartclip/template.md 3. 素材由客户平台上传并保存为公网 URL。 4. 合成：POST https://xiaoapis.com/api/smartclip/news_mixcut?action=create 。必填 key、styleId、title（3 到 1800 字）、materials、callback_url。materials 至少 1 条，type 为 image 或 video，带 fileUrl。图片按 2 秒估算时长。可选 processRules.videoDuration（5 到 300 秒）和 materialComposition（random 或 order）。文档 https://xiaoapis.com/model/smartclip/news_mixcut.md 5. 轮询 GET https://xiaoapis.com/api/smartclip/task_query 。completed 取 video_url，failed 返回失败原因。查询不扣费。文档 https://xiaoapis.com/model/smartclip/task_query.md 约束：API Key 只放服务端；POST JSON 时 key 写在 JSON Body。不要传入 realMan 或 oralMixCutting 的模板。素材地址不能互相重名。
04 · scene=realMan
视频包装
已有成片 + 字幕 / 特效 / 封面。最终接口是 realman_broadcast。
-
1
保存成片地址
客户已经有完整视频。上传和存储由客户平台自己做，剪辑时只提交视频地址。
-
2
选取模板
包装复用 scene=realMan 的模板，和真人口播同一套模板场景。
-
3
读取模板要求
用户选定模板后拉详情，按图层要求准备字幕、特效或封面素材。
-
4
调用同一合成接口
把视频、模板和相关素材交给 realman_broadcast。它和真人口播是同一个接口，输入不同：这里没有口播文案和音色。
请在客户自己的业务后端实现「视频包装」。前端只调用客户路由 POST /api/smartclip/package。它和真人口播调用同一个销豹接口，输入不同：只要已有成片、模板和包装素材，不要口播文案，不要音色。 先读这些 Markdown，再写代码，字段以文档为准，不要编造： - 模板列表 https://xiaoapis.com/model/smartclip/template.md - 模板详情 https://xiaoapis.com/model/smartclip/template_detail.md - 真人口播合成 https://xiaoapis.com/model/smartclip/realman_broadcast.md - 任务查询 https://xiaoapis.com/model/smartclip/task_query.md 按这个顺序做： 1. 成片地址由客户自己保存。剪辑时只提交公网 videoUrl。 2. 模板：POST https://xiaoapis.com/api/smartclip/template ，scene 固定 realMan。选定后 POST https://xiaoapis.com/api/smartclip/template_detail ，JSON 带 id，按图层准备字幕、特效或封面。文档 https://xiaoapis.com/model/smartclip/template.md 和 https://xiaoapis.com/model/smartclip/template_detail.md 3. 合成：POST https://xiaoapis.com/api/smartclip/realman_broadcast?action=create 。必填 key、styleId、videoUrl、callback_url。包装素材放进 materials、subtitle、packRules 或 structLayers，字段以文档为准。文档 https://xiaoapis.com/model/smartclip/realman_broadcast.md 4. 轮询 GET https://xiaoapis.com/api/smartclip/task_query 。文档 https://xiaoapis.com/model/smartclip/task_query.md 约束：API Key 只放服务端；POST JSON 时 key 写在 JSON Body。videoUrl、素材地址、背景音乐地址不能重名。不要把这个接口做成第二次口播配音。做完给出客户路由和一份只含成片地址与模板的请求示例。
对照
四种模式差在哪
| 功能 | 真人口播 | 素材混剪 | 新闻混剪 | 视频包装 |
|---|---|---|---|---|
| 口播文案 | 要 | 要 | 要 | 不要 |
| 数字人 / 真人视频 | 要 | 不要 | 不要 | 要 |
| 音色 | 要 | 要 | 不要 | 不要 |
| 模板列表 | 要 | 要 | 要 | 要 |
| 模板详情 | 要 | 按素材要求 | 按素材要求 | 要 |
| 客户上传素材 | 要 | 要 | 要 | 要 |
| scene | realMan | oralMixCutting | newsMixCutting | realMan |
| 最终接口 | realman_broadcast | broadcast_mixcut | news_mixcut | realman_broadcast |
接口清单
这一页会用到的接口
客户封装
销豹接口留在客户后端
下面这些路径是建议客户在自己的业务后端封装的名字，不是销豹的开放地址。API Key 只放在客户服务端。
客户前端
客户业务后端
销豹 AI API
成片地址
GET /api/smartclip/templates转发模板列表，并按模式带上 sceneGET /api/smartclip/template/{id}转发模板详情POST /api/smartclip/realman真人口播，内部调用 realman_broadcastPOST /api/smartclip/mixcut素材混剪，内部调用 broadcast_mixcutPOST /api/smartclip/news新闻混剪，内部调用 news_mixcutPOST /api/smartclip/package视频包装，内部仍调用 realman_broadcast
请先搭客户自己的业务后端，把销豹智能剪辑包在里面。前端只能调用下面这些客户路由，不能看到 API Key，也不能直接请求 xiaoapis.com。
先读这些 Markdown，再写代码，字段以文档为准，不要编造：
- 模板列表 https://xiaoapis.com/model/smartclip/template.md
- 模板详情 https://xiaoapis.com/model/smartclip/template_detail.md
- 真人口播 https://xiaoapis.com/model/smartclip/realman_broadcast.md
- 素材混剪 https://xiaoapis.com/model/smartclip/broadcast_mixcut.md
- 新闻混剪 https://xiaoapis.com/model/smartclip/news_mixcut.md
- 任务查询 https://xiaoapis.com/model/smartclip/task_query.md
客户路由（这些不是销豹地址）：
- GET /api/smartclip/templates ：转发模板列表，query 带 scene
- GET /api/smartclip/template/{id} ：转发模板详情
- POST /api/smartclip/realman ：真人口播，内部调 realman_broadcast，scene=realMan
- POST /api/smartclip/mixcut ：素材混剪，内部调 broadcast_mixcut，scene=oralMixCutting
- POST /api/smartclip/news ：新闻混剪，内部调 news_mixcut，scene=newsMixCutting
- POST /api/smartclip/package ：视频包装，内部仍调 realman_broadcast，scene=realMan，但不接收文案和音色
销豹地址：
- POST https://xiaoapis.com/api/smartclip/template 文档 https://xiaoapis.com/model/smartclip/template.md
- POST https://xiaoapis.com/api/smartclip/template_detail 文档 https://xiaoapis.com/model/smartclip/template_detail.md
- POST https://xiaoapis.com/api/smartclip/realman_broadcast 文档 https://xiaoapis.com/model/smartclip/realman_broadcast.md
- POST https://xiaoapis.com/api/smartclip/broadcast_mixcut 文档 https://xiaoapis.com/model/smartclip/broadcast_mixcut.md
- POST https://xiaoapis.com/api/smartclip/news_mixcut 文档 https://xiaoapis.com/model/smartclip/news_mixcut.md
- GET https://xiaoapis.com/api/smartclip/task_query 文档 https://xiaoapis.com/model/smartclip/task_query.md
约束：API Key 放服务端环境变量。POST JSON 时 key 写在 JSON Body。模板列表按 scene 缓存。用户点开某个模板再读详情。视频和音色在客户库里只存一次，剪辑时引用。scene 和接口必须成对，不能混用。先只做真人口播这一条，通了再加另外三种。对接时盯住这几件事
- 模板决定素材
- 先拿模板，再读详情，最后合成。格式、数量、尺寸、时长不符合要求，任务会失败。校验放在客户上传阶段。
- scene 不能改
- realMan 只给真人口播和视频包装。oralMixCutting 只给素材混剪。newsMixCutting 只给新闻混剪。
- 模板列表可以缓存
- 客户平台缓存模板列表，不必每次打开页面都请求。用户选定某一个模板时再读详情。
- 视频和音色只存一次
- 真人口播保存用户上传的视频地址。音色记录也保存在客户系统。剪辑时引用，不重复克隆。
最小落地路径
先只做真人口播：文案、真人视频、音色、模板、模板详情、素材，然后调用 realman_broadcast，再查询成片。这条通了，再加素材混剪、新闻混剪和视频包装。问题会落在某一种模式的参数上，而不是四种一起排查。
前置模块
文案和配音可以接在剪辑前面
视频文案提取
已有视频或分享链接时，先取出可播放地址和口播正文，用户确认或改完，再进入配音或剪辑。演示在 视频文案，解析看 /doc/43，正文看 /doc/28。
请在客户自己的业务后端实现「视频文案提取」。前端只调客户接口，不要接触销豹 API Key。 先读这些 Markdown，再写代码，字段以文档为准，不要编造： - 视频解析 https://xiaoapis.com/model/video/videoparse.md - 视频文案 https://xiaoapis.com/model/video/text.md 分两步，不要混成一个接口： 1. 用户贴的是分享链接或口令时，先解析出视频地址：GET 或 POST https://xiaoapis.com/api/video/videoparse ，参数 url 为完整链接、短链或带链接的分享口令。flat 默认可用 2。这个接口返回标题、描述、封面和无水印视频地址，不返回口播正文。解析失败不扣费。文档 https://xiaoapis.com/model/video/videoparse.md 2. 口播正文：POST https://xiaoapis.com/api/video/text 。content 传视频或音频公网 URL。不带 taskId 是提交，带 taskId（也兼容 taskid、task_id）是查询。完成后读取 resultText，交给用户确认。language 可选，默认自动识别。文档 https://xiaoapis.com/model/video/text.md 约束：API Key 只放服务端。只解析用户有权使用的内容，不要把解析结果做成下载站。确认后的文案才进入配音或剪辑。
声音克隆
创建音色并存在客户系统里。后面的配音和剪辑直接引用这个音色，不必每次重做。接口是 /doc/9，查询是 /doc/47。
请在客户自己的业务后端实现「声音克隆」，并把音色记录存进客户数据库。前端只提交音频地址和名称。 先读这些 Markdown，再写代码，字段以文档为准，不要编造： - 声音克隆 https://xiaoapis.com/model/aihuman/clonevoice.md - 克隆查询 https://xiaoapis.com/model/aihuman/clonevoice_query.md 1. 创建：POST https://xiaoapis.com/api/aihuman/clonevoice 。audio_url 为原音频公网地址。name 可选。lang 只用 zh-cn 或 en，默认 zh-cn。notify 为客户自己的回调地址。文档 https://xiaoapis.com/model/aihuman/clonevoice.md 2. 查询：GET https://xiaoapis.com/api/aihuman/clonevoice_query?task_id=创建时返回的任务ID&key=密钥 。完成后把 voice_id 存下来。查询不扣费。文档 https://xiaoapis.com/model/aihuman/clonevoice_query.md 3. 剪辑和配音只引用已保存的 voice_id，不要每次重新克隆。 约束：API Key 只放服务端环境变量，POST JSON 时 key 写在 JSON Body。做完说明音色记录存在哪、失败时怎么把 fail_reason 返回给用户。
语音合成
文本加音色合成音频，再把音频地址交给素材混剪。接口是 /doc/10，查询是 /doc/45。配音演示在 AI 配音。
请在客户自己的业务后端实现「语音合成」。前端提交确认后的文本和已保存的音色 ID，后端返回音频地址。 先读这些 Markdown，再写代码，字段以文档为准，不要编造： - 语音合成 https://xiaoapis.com/model/aihuman/tts.md - 合成查询 https://xiaoapis.com/model/aihuman/tts_query.md - 素材混剪 https://xiaoapis.com/model/smartclip/broadcast_mixcut.md 1. 创建：POST https://xiaoapis.com/api/aihuman/tts 。text 不超过 2000 字。voice_type 为 custom（克隆音色）或 public（系统音色）。voice_id 用客户已保存的音色，不要临时克隆。克隆音色的 lang 只用 zh-cn 或 en。volume 和 speed 取值 0 到 2，默认 1。notify 为客户回调地址。文档 https://xiaoapis.com/model/aihuman/tts.md 2. 查询：GET https://xiaoapis.com/api/aihuman/tts_query?task_id=创建时返回的任务ID&key=密钥 。完成后取 audio_url。查询不扣费。文档 https://xiaoapis.com/model/aihuman/tts_query.md 3. 若下一步是素材混剪，把这个 audio_url 作为 broadcast_mixcut 的 audioUrl，不要把文本和 speakerId 直接塞进混剪接口。文档 https://xiaoapis.com/model/smartclip/broadcast_mixcut.md 约束：API Key 只放服务端。
两条组合
视频 → 提取文案 → 确认 → 配音 → 剪辑 → 成片。也可以从文案直接开始：文案 → 配音 → 选模板和素材 → 剪辑。
请把下面两条链路接到客户自己的后端，前端只调客户接口。API Key 只放服务端。每一步先读对应 Markdown，不要编造字段，也不要跳过用户确认。 先读这些 Markdown： - 视频解析 https://xiaoapis.com/model/video/videoparse.md - 视频文案 https://xiaoapis.com/model/video/text.md - 语音合成 https://xiaoapis.com/model/aihuman/tts.md - 合成查询 https://xiaoapis.com/model/aihuman/tts_query.md - 模板列表 https://xiaoapis.com/model/smartclip/template.md - 真人口播 https://xiaoapis.com/model/smartclip/realman_broadcast.md - 素材混剪 https://xiaoapis.com/model/smartclip/broadcast_mixcut.md - 新闻混剪 https://xiaoapis.com/model/smartclip/news_mixcut.md - 任务查询 https://xiaoapis.com/model/smartclip/task_query.md 链路 A：已有视频或分享链接。 1. 分享链接先 POST/GET https://xiaoapis.com/api/video/videoparse 取出视频地址。文档 https://xiaoapis.com/model/video/videoparse.md 2. POST https://xiaoapis.com/api/video/text 抽出 resultText，让用户确认或修改。文档 https://xiaoapis.com/model/video/text.md 3. 用已保存音色 POST https://xiaoapis.com/api/aihuman/tts ，再查 https://xiaoapis.com/api/aihuman/tts_query 得到 audio_url。文档 https://xiaoapis.com/model/aihuman/tts.md 和 https://xiaoapis.com/model/aihuman/tts_query.md 4. 按用户选的模式剪辑，最后 GET https://xiaoapis.com/api/smartclip/task_query 取成片。文档 https://xiaoapis.com/model/smartclip/task_query.md 链路 B：用户直接给文案。从第 3 步开始，然后选模板和素材，再剪辑。 模式不要混用：真人口播 scene=realMan，接口 realman_broadcast，文档 https://xiaoapis.com/model/smartclip/realman_broadcast.md ；素材混剪 scene=oralMixCutting，接口 broadcast_mixcut，声音走 audioUrl，文档 https://xiaoapis.com/model/smartclip/broadcast_mixcut.md ；新闻混剪 scene=newsMixCutting，接口 news_mixcut，不要音色，文档 https://xiaoapis.com/model/smartclip/news_mixcut.md 。模板列表文档 https://xiaoapis.com/model/smartclip/template.md