openclip-clipping

OpenClip：将长视频剪辑成短视频

OpenClip 的核心工作流：提交一段长视频，获取按排名排列的“爆款时刻”，包括标题、吸引点、社交媒体文案和片段 URL。这是付费工作流，需要有效的 OpenClip 订阅和额度（额度按处理分钟数计算）。

每个步骤都是异步的。务必轮询，切勿假设调用已完成。

设置（一次性）

OpenClip 是一个远程 MCP 服务，地址为 https://openclip.app/mcp。出现 OAuth 提示时，使用你的 OpenClip 账户登录，无需复制 API 密钥。

• Claude Code： claude mcp add --transport http openclip https://openclip.app/mcp，然后运行 /mcp 进行授权。
• Claude Desktop / web： 打开设置，选择连接器，再选择“添加自定义连接器”，粘贴 URL 并登录。
• Cursor（.cursor/mcp.json）：{ "mcpServers": { "openclip": { "url": "https://openclip.app/mcp" } } }
• 仅支持请求头的客户端： 在 openclip.app/settings/connect 创建 MCP 令牌，然后使用 Authorization: Bearer <token> 连接到 https://openclip.app/mcp/key。

健全性检查：调用 get_account，确认 credits_remaining > 0。

工作流

1. 提交。 submit_video(url) 会返回一个 job_id，其状态为 status: "queued"。 如果不确定某个来源 URL 是否受支持，请先调用 list_supported_providers。 对于本地文件：调用 create_upload(filename, content_type)，上传文件字节，然后调用 complete_upload（此操作会启动这个付费工作流）。
2. 轮询。 持续调用 get_video_status(job_id)，直到 status 为 completed 或终止状态。 在状态变为 completed 之前，切勿调用 list_clips。
3. 列出。 list_clips(job_id) 会返回爆款时刻。
4. 渲染（可选）。 render_clip(moment_id, caption_preset) 会将字幕嵌入视频。此操作同样是异步的，参见 openclip-captions 技能。

正确读取状态

这是 Agent 容易出错的地方。经过身份验证后，submit_video 始终会成功。 它会将任务加入队列，但不会预先检查订阅或额度。之后会在 get_video_status 中以状态值而非错误的形式显示是否通过检查：

• pending、downloading、processing - 正在进行中，继续轮询。
• completed - 已到终止状态，现在调用 list_clips。
• failed - 已到终止状态。如果在提交后几乎立即出现，通常表示没有有效订阅。告知用户前往 openclip.app 订阅。
• pending_credits - 团队额度不足。告知用户充值。
• download_failed（位于嵌套字段 video.status 中）- 无法获取来源 URL。请用户检查链接。

不要期待收到同步的“你需要订阅”错误。读取状态并给出建议。

video.progress 是粗略值，并非平滑变化的百分比。失败时约为 0，下载期间为个位数，上传完成后约为 10，处理中约为 20，完成后为 100。控制流程时使用 status，切勿使用 progress。

时刻的内容

list_clips 返回的每个条目：

• id - hashid，将其传给 render_clip。
• title、hook、quote、social_copy、platforms、category - 发布时可配套使用的文案。
• start_time_ms、end_time_ms、duration_ms - 时间单位为毫秒。
• virality_score - 0 到 10。除非用户另有要求，否则按此分数排序。
• viral_score_details - 子分数为 0 到 100：吸引点强度、可分享性、可重看性、意外性、情感冲击。使用这些分数解释片段排名的原因。
• thumbnail_url，以及资源 clip {url, size_bytes, type}、clip_watermarked 和 render_clip 成功后的 rendered_clip {url, size_bytes}。

片段 URL 是永久 CDN 链接，不是签名链接，也不会过期。

可复用预设

若要让重复运行保持一致（相同的追踪模型、字幕预设、构图和徽标水印），请使用 create_agent 保存处理 Agent，然后将其传给 submit_video。 describe_agent_settings 会说明每个嵌套字段及其允许值。update_agent 只会更新你提供的字段。使用 create_agent_logo_upload 和 set_agent_logo 添加 水印（最大 2 MB）。get_usage 会报告额度余额和近期活动。

错误

这些是 MCP 工具，而不是 REST API。失败时会返回带有 isError: true 的工具结果，以及纯文本消息。没有 HTTP 状态码，也没有 JSON 错误封装。

• "Not authenticated. Reconnect your OpenClip token." - 重新连接连接器，或为 /mcp/key 路径重新生成 MCP 令牌。
• "Job not found." - job_id 错误、已过期，或属于其他账号。如果它来自旧会话，请重新提交。
• "Viral moment not found." - moment_id 错误。使用 list_clips 重新获取。
• "Video not yet available. Check get_video_status for progress." - 你调用 list_clips 太早了。继续轮询 get_video_status。
• 验证消息会以消息文本的形式返回。修正参数后重试。

规则

• 始终轮询。不要假设提交后会立即完成。
• 按 virality_score 排序，分数越高越好。
• 时间单位为毫秒。
• **此 API 不支持项目和文件夹。**不要承诺提供这些功能。
• list_videos 会显示账号中已有的视频。

示例提示词与操作

• “剪辑这个：” - 调用 submit_video(url)，轮询 get_video_status，然后调用 list_clips。
• “列出 job_... 中排名前 3 的精彩片段” - 调用 list_clips，按 virality_score 排序，取前 3 个。
• “为什么那个最好？” - 查看该片段的 viral_score_details。
• “把我上次上传的视频制作成 Shorts” - 调用 list_videos，选中视频，提交，轮询，然后列出片段。

相关

为字幕添加样式并烧录到视频中，可使用 openclip-captions。将长视频转换为适用于多个平台的完整工作流，请使用 openclip-repurpose。无需订阅即可免费修剪和裁剪视频，请使用 openclip-video-editing。