SupoClip REST API完全参考:API密钥认证+全端点清单+调用示例

原创2026-10-12 16:49:151,441 阅读

SupoClip REST API完全参考:API密钥认证+全端点清单+调用示例

SupoClip 是一个开源的 AI 视频剪辑工具(OpusClip 的开源替代品),可以把长视频自动切分成带字幕的竖版短视频。本文是 SupoClip REST API 的完整参考,围绕 API 密钥认证、全端点清单 和 调用示例 三部分展开,帮你用脚本或 AI Agent 自动完成"提交视频 → 生成剪辑 → 导出成品"的全流程。

SupoClip 将长视频自动切分成多条竖版短视频的核心能力

SupoClip API 的两层结构:先看懂再调用

调用 API 前,先理解 SupoClip 的两层架构:

  • 前端代理层(frontend/src/app/api):浏览器通常访问这一层,它携带会话上下文后转发请求
  • 后端 FastAPI 层(backend/src/api/routes):真正干活的 REST 端点,API 密钥直接认证的也是这一层

官方文档在 docs/api-reference.md,自托管部署后还可访问 http://localhost:8000/docs 查看 FastAPI 自动生成的交互式文档,支持在线调试。

SupoClip 剪辑台界面:API 生成的字幕、字体和剪辑参数都在这里调整

三步完成 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 是否正确

延伸阅读

掌握以上认证方式和端点清单后,你就可以把 SupoClip 接入自己的自动化流水线:定时抓取视频、批量生成剪辑、按品牌模板统一字幕风格,全部通过 REST API 完成。

登录后查看全文
supoclip