SupoClip REST API完全参考:API密钥认证+全端点清单+调用示例
SupoClip REST API完全参考:API密钥认证+全端点清单+调用示例
SupoClip 是一个开源的 AI 视频剪辑工具(OpusClip 的开源替代品),可以把长视频自动切分成带字幕的竖版短视频。本文是 SupoClip REST API 的完整参考,围绕 API 密钥认证、全端点清单 和 调用示例 三部分展开,帮你用脚本或 AI Agent 自动完成"提交视频 → 生成剪辑 → 导出成品"的全流程。
SupoClip API 的两层结构:先看懂再调用
调用 API 前,先理解 SupoClip 的两层架构:
- 前端代理层(frontend/src/app/api):浏览器通常访问这一层,它携带会话上下文后转发请求
- 后端 FastAPI 层(backend/src/api/routes):真正干活的 REST 端点,API 密钥直接认证的也是这一层
官方文档在 docs/api-reference.md,自托管部署后还可访问 http://localhost:8000/docs 查看 FastAPI 自动生成的交互式文档,支持在线调试。
三步完成 API 密钥认证 🔑
第一步:创建一个 API 密钥
在应用内进入 Settings → Agents & API(/settings/api-keys)创建密钥。注意两条安全设计:
- 明文
sk_...密钥只显示一次,之后无法再次查看 - 服务端只存储其 SHA-256 哈希(见 auth_headers.py),泄露的密钥无法被用来创建更多密钥
API 密钥管理端点在 api_keys.py:
| 端点 | 作用 |
|---|---|
GET /api-keys/ |
列出当前用户的所有密钥(仅元数据) |
POST /api-keys/ |
创建新密钥,明文只返回一次 |
DELETE /api-keys/{key_id} |
吊销密钥,立即生效 |
第二步:在请求头中携带密钥
API 密钥支持两种等价的传递方式:
# 方式一:Authorization Bearer
curl https://api.supoclip.com/tasks/ \
-H "Authorization: Bearer sk_..."
# 方式二:x-api-key 请求头
curl https://api.supoclip.com/tasks/ \
-H "x-api-key: sk_..."
第三步:确认密钥的可用范围
API 密钥可认证 /tasks/*、/fonts 和 /upload 三大类端点;/api-keys 和 /account 等管理端点只接受前端签名的会话头,刻意不接受密钥,防止密钥被滥用。
💡 如果你用的是 Claude、Cursor 等 AI Agent,可以直接使用仓库自带的 SupoClip MCP Server,它已封装好这套 API,无需手写请求。
REST API 全端点清单 📋
以下端点清单整理自后端源码,可直接对照查阅。
任务生命周期端点(/tasks)
源码:tasks.py
| 端点 | 说明 |
|---|---|
GET /tasks/ |
列出当前用户的所有任务 |
POST /tasks/ |
创建剪辑任务并入队处理,立即返回 task_id |
GET /tasks/{task_id} |
查看任务详情 |
GET /tasks/{task_id}/progress |
SSE 进度流(Server-Sent Events,非 WebSocket) |
PATCH /tasks/{task_id} |
更新任务元数据 |
DELETE /tasks/{task_id} |
删除任务 |
POST /tasks/{task_id}/cancel |
取消进行中的任务 |
POST /tasks/{task_id}/resume |
恢复已取消或出错的任务 |
GET /tasks/billing/summary |
查看计费与用量摘要 |
POST /tasks/{task_id}/share / DELETE |
创建 / 取消任务分享链接 |
GET /tasks/shared/{share_token} |
通过分享 token 查看任务 |
GET /tasks/metrics/performance |
聚合性能指标 |
GET /tasks/dead-letter/list |
查看失败任务(死信队列) |
进度端点使用 SSE 长连接,前端用 EventSource 订阅,Redis 中的进度更新会实时推送,无需轮询。
剪辑(Clip)操作端点
| 端点 | 说明 |
|---|---|
GET /tasks/{task_id}/clips |
列出已生成的剪辑 |
PATCH /tasks/{task_id}/clips/{clip_id} |
编辑剪辑(入出点、参数等) |
POST /tasks/{task_id}/clips/{clip_id}/split |
拆分剪辑 |
POST /tasks/{task_id}/clips/merge |
合并多个剪辑 |
PATCH /tasks/{task_id}/clips/{clip_id}/captions |
更新字幕文本与样式 |
POST /tasks/{task_id}/clips/{clip_id}/regenerate |
重新渲染剪辑 |
DELETE /tasks/{task_id}/clips/{clip_id} |
删除剪辑 |
GET /tasks/{task_id}/clips/{clip_id}/file |
获取剪辑视频文件 |
GET /tasks/{task_id}/clips/{clip_id}/export |
按平台预设(如竖版 9:16)导出 |
POST /tasks/{task_id}/settings |
应用任务级设置(字体、字幕模板等) |
剪辑台(Editor)深度编辑端点
源码:editor.py,对应上文截图中的可视化剪辑台:
GET /tasks/{task_id}/clips/{clip_id}/editor— 加载剪辑台文档POST .../editor/prepare— 准备编辑素材(202 异步任务)PATCH .../editor— 提交剪辑台修改GET .../editor/media/{asset}— 获取编辑媒体资源POST .../editor/exports/GET|DELETE .../editor/exports/{job_id}— 创建 / 查询 / 删除导出任务GET .../editor/exports/{job_id}/file— 下载导出文件POST /tasks/{task_id}/editor/combine— 合并多段为一条
媒体与上传端点
源码:media.py
GET /fonts— 列出可用字体GET /fonts/{font_name}— 下载字体文件POST /fonts/upload— 上传自定义字体DELETE /fonts/{font_name}— 删除字体GET /transitions— 列出转场素材GET /caption-templates— 列出字幕模板GET /broll/status— B-roll 集成状态POST /upload— 上传源视频
其他端点
| 端点 | 说明 | 源码 |
|---|---|---|
POST /feedback |
提交产品反馈 | feedback.py |
POST /subscription-email |
触发订阅相关邮件 | billing.py |
GET /health |
校验管理员访问与后端连通性 | admin.py |
POST /account/password-reset-email |
发送密码重置邮件 | account.py |
调用示例:从零创建剪辑任务 🚀
完整流程:上传/提交视频 → 轮询 SSE 进度 → 拉取剪辑 → 导出。
创建任务只需一个请求体,核心是 source.url:
curl -X POST https://api.supoclip.com/tasks/ \
-H "x-api-key: sk_..." \
-H "Content-Type: application/json" \
-d '{
"source": { "url": "https://www.youtube.com/watch?v=xxxxx" },
"font_options": { "font_family": "Anton", "font_size": 54 },
"caption_template": "default",
"processing_mode": "balanced",
"output_format": "vertical",
"add_subtitles": true
}'
成功返回:
{
"task_id": "...",
"job_id": "...",
"message": "Task created and queued for processing"
}
参数说明:processing_mode 可选 fast / balanced / quality;output_format 默认 vertical;YouTube 链接会先做时长预检,超出套餐限制会直接返回 402。
拿到 task_id 后,订阅进度流即可实时看到处理状态:
curl -N https://api.supoclip.com/tasks/{task_id}/progress \
-H "x-api-key: sk_..."
任务完成后,用 GET /tasks/{task_id}/clips 拉取所有剪辑,再用 GET /tasks/{task_id}/clips/{clip_id}/export 按平台预设导出成品。
常见状态码避坑指南 ⚠️
| 状态码 | 含义 | 建议 |
|---|---|---|
402 |
免费额度用完(SUBSCRIPTION_REQUIRED) |
升级套餐后重试 |
409 |
并发创建冲突,带 Retry-After: 1 头 |
按提示延迟 1 秒重试 |
400 |
缺少 source.url 等必填参数 |
检查请求体 |
404 |
任务 / 剪辑 / 密钥不存在 | 核对 ID 是否正确 |
延伸阅读
- 完整 API 参考:docs/api-reference.md
- 系统架构:docs/architecture.md
- 自托管部署:docs/setup.md
- 故障排查:docs/troubleshooting.md
- AI Agent 集成:mcp/README.md
掌握以上认证方式和端点清单后,你就可以把 SupoClip 接入自己的自动化流水线:定时抓取视频、批量生成剪辑、按品牌模板统一字幕风格,全部通过 REST API 完成。

