openclip

OpenClip：通过 Agent 编辑视频

OpenClip 是一个视频编辑 MCP 服务。其主打工作流可以将长视频剪辑成带字幕、经过排名的短片段。完整的 /mcp 和 /mcp/key 端点提供六组共 31 个工具，详见下方。ChatGPT 应用仅提供经过审核的剪辑工作流子集。

• 文档：search_docs 用于搜索 OpenClip 的产品功能、设置、工作流、集成和故障排查指南。产品行为不明确时，请调用此工具。
• 剪辑工作流：submit_video、get_video_status、list_clips、render_clip、get_render_status、list_caption_presets、get_transcript、list_supported_providers、list_videos。
• 上传：create_upload、complete_upload（请注意下方的特殊情况：complete_upload 会启动付费工作流；免费工具可跳过此步骤）。
• 免费媒体工具（仅需账户，无需订阅）：transcribe、edit_video、convert_media、extract_thumbnails、edit_image、remove_background、get_tool_job_status。
• UGC 生成：generate_ugc、get_ugc_job_status、list_ugc_creators、list_ugc_jobs。
• 账户和预设：get_account、get_usage、list_agents、create_agent、update_agent、describe_agent_settings、create_agent_logo_upload、set_agent_logo。

设置（仅需一次）

远程服务首选 OAuth 一键授权：将服务 URL（https://openclip.app/mcp）粘贴到客户端，然后使用 OpenClip 账户登录，无需复制令牌。

1. 将远程服务添加到 Agent 中（服务 URL：https://openclip.app/mcp）：
   • Claude Desktop： Settings → Connectors → Add custom connector → 粘贴 https://openclip.app/mcp → Connect → 登录。
   • Claude Code： claude mcp add --transport http openclip https://openclip.app/mcp， 然后运行 /mcp 并在浏览器中授权。
   • Cursor（.cursor/mcp.json）： { "mcpServers": { "openclip": { "url": "https://openclip.app/mcp" } } }，Cursor 会运行 OAuth。
2. **手动 Bearer 令牌（替代方式，适用于仅支持请求头的客户端或程序化客户端）：**在 openclip.app/settings/connect 生成一个 MCP 令牌（“Generate MCP token”，仅显示一次），并使用该令牌作为 Bearer 请求头连接到 /mcp/key 端点：
   • Claude Code： claude mcp add --transport http openclip https://openclip.app/mcp/key --header "Authorization: Bearer <token>"
   • Cursor（.cursor/mcp.json）： { "mcpServers": { "openclip": { "url": "https://openclip.app/mcp/key", "headers": { "Authorization": "Bearer <token>" } } } }
   • **任何 MCP 客户端：**向 https://openclip.app/mcp/key 发送 POST 请求，并设置请求头 Authorization: Bearer <token>。
3. 简单检查：调用 get_account。确认 credits_remaining > 0。

（仅适用于自托管/开发：使用 php artisan mcp:start openclip 运行本地 stdio 服务。）

工作流程（处理为异步，务必轮询）

1. 提交：submit_video(url) → 返回带有 status:"queued" 的 job_id。经过身份验证后，此操作始终会成功（将任务加入队列），不会预先检查订阅或积分。
2. 轮询状态：调用 get_video_status(job_id)，直到 status 为 completed（或 failed）。 完成之前不要调用 list_clips。读取 status 获取实际状态：
   • failed（通常在提交后几乎立即出现）通常表示没有有效订阅——建议用户前往 openclip.app 订阅。
   • pending_credits 表示团队积分不足，建议用户充值。
   • download_failed 表示无法获取源 URL，请让用户检查链接。
3. 列出片段：list_clips(job_id) → 返回热门时刻及其 virality_score（0-10）、标题/吸引点、开始/结束时间（毫秒），以及 clip / rendered_clip URL。
4. （可选）渲染带字幕的片段：render_clip(moment_id, caption_preset)。此操作也是异步的，请轮询 list_clips，并查看对应时刻的 rendered_clip，等待生成最终 URL。预设键： list_caption_presets。

免费媒体工具（无需订阅）

transcribe、edit_video、convert_media、extract_thumbnails、edit_image 和 remove_background 均为免费工具：只需有账号，无需订阅或点数。 它们都遵循相同的异步模式：

1. 获取文件：对于本地文件，调用 create_upload(filename, content_type)，将 字节数据 PUT 到返回的 upload_url，并将返回的 id 用作 file/video。 免费工具不要调用 complete_upload——这会启动付费剪辑流程；免费工具会直接读取上传的文件。（list_videos 中已有的视频也可用作输入。）
2. 调用工具。它会返回一个 tool_job hashid，状态为 status: "queued"。
3. 每隔 5-10 秒轮询一次 get_tool_job_status(tool_job)：queued/processing 表示仍在处理中，completed/failed 表示已到终态。状态为 completed 时，会返回永久有效的 CDN outputs URL（例如，transcribe 返回 json/srt/vtt，extract_thumbnails 返回包含帧的 zip 文件）。状态为 failed 时会返回 error。

操作速查表（完整参数见 reference.md）：edit_video 执行一项 operation，可选裁剪、截取、旋转、调整大小、压缩或静音；convert_media 可转换为 mp4/webm/mov/mkv、gif 或 mp3/aac/wav/flac；edit_image 可压缩、调整大小或裁剪；remove_background 会返回透明 PNG。免费使用有每日速率限制和单文件大小上限；错误文本会说明如何解除限制。

注意区分两种转录：transcribe 是用于已上传文件的免费工具；get_transcript 会读取经过付费剪辑流程的视频的带时间码转录文本（支持按句子或单词级别使用 start_ms/end_ms 指定时间范围）。

UGC 生成

generate_ugc 根据创意简报生成一段较短（约 7-12 秒）的竖屏 UGC 风格片段（不是散文提示词：需使用 character 等结构化字段，或使用服务器端的 brief_name 预设）。免费账号每天可生成一次；付费账号按渲染秒数扣除点数。它会返回一个 ugc_job hashid；每隔 10-15 秒轮询一次 get_ugc_job_status（queued/rendering 表示仍在处理中，completed 会返回 video_url + result_meta，failed 会返回 error）。渲染任务开销较大：预计需要几分钟。

生成前，调用 list_ugc_creators，查看团队可用的 creator 和 start_frame 值（按细分领域分组的精选名单，以及团队保存的创作者）。使用 list_ugc_jobs 查看团队过去的 UGC 片段，或查找要轮询的 ugc_job id。

可重复使用的预设（Agent）

如需确保重复工作流保持一致（使用相同的跟踪模型、字幕预设和 Logo 水印），请使用 create_agent 保存一次处理 Agent，并将其传递给 submit_video。describe_agent_settings 会说明所有嵌套字段和允许的值；update_agent 只会更新你发送的字段；create_agent_logo_upload + set_agent_logo 用于添加水印（最大 2 MB）。get_usage 会报告点数余额（点数按处理分钟数计算）和近期活动。

规则与注意事项

• 始终轮询；不要假设提交后会立即完成。循环调用 get_video_status 进行轮询。
• 除非用户另有说明，否则按 virality_score 选择片段（越高越好）。
• 时间单位为毫秒。clip.url 是永久有效的 CDN URL（不会签名或过期）。
• 无论订阅或点数状态如何，submit_video 都会将任务加入队列；限制会在稍后的 get_video_status 中显示（failed = 无订阅，pending_credits = 点数不足）。请读取状态并据此向用户提供建议，不要期待同步返回“订阅”错误。
• 此 API 不支持项目/文件夹，不要承诺提供此类功能。

错误处理

这些是 MCP 工具，不是 REST/HTTP API。工具调用失败时，会返回常规工具结果，其中包含 isError: true 和简短的纯文本消息（没有 HTTP 401/402/403/422 状态码，也没有 JSON 错误封装）。请阅读消息文本并据此处理：

• "Not authenticated. Reconnect your OpenClip token."，表示连接未携带有效身份 → 重新连接。对于 OAuth 路径，请重新运行连接器登录（例如，在 Claude Code 中运行 /mcp）；对于手动 /mcp/key 路径，请在连接页面重新生成 MCP token，并使用新的 Bearer token 重新添加服务。（如果 token 缺少 mcp:use scope/ability，会在任何工具运行之前被传输层拒绝，解决方法相同：重新连接 / 重新生成 token。）
• "Job not found."（get_video_status、list_clips），表示 job_id 有误、来自其他账号或已过期 → 重新检查传入的 id；如果它来自之前的会话，请重新提交视频。
• "Viral moment not found."（render_clip），表示 moment_id 有误或属于其他账号 → 使用 list_clips 重新获取片段，并使用该响应中的 id。
• "Video not yet available. Check get_video_status for progress."（list_clips），表示任务尚未生成视频记录（仍在排队 / 下载）→ 继续轮询 get_video_status，仅在 status 为 completed 后调用 list_clips。
• 验证消息（例如，url 无效 / 缺失，或 caption_preset 未知），验证错误文本会作为工具消息返回 → 修正有问题的参数并重试。
• 订阅 / 积分在此处不属于错误，它们会显示为 get_video_status 的 status 值（failed = 没有订阅 → 订阅；pending_credits = 积分不足 → 充值），而不是工具错误。请参阅上文的“The loop”。

示例提示词 → 操作

• “剪辑这个视频：” → submit_video(url)，轮询 get_video_status，然后调用 list_clips。
• “给我 job_… 中最精彩的 3 个片段” → 调用 list_clips，按 virality_score 排序，取前 3 个。
• “用 Beast 字幕渲染片段 m_…” → render_clip(m_…, caption_preset="beast")，然后轮询。
• “转录这段录音” → create_upload，PUT 字节，transcribe(video)，轮询 get_tool_job_status（不要调用 complete_upload）。
• “将其转换为 gif” / “压缩此视频” → create_upload，PUT 字节，convert_media(file, to="gif") / edit_video(file, operation="compress")，然后轮询。
• “移除这张图片的背景” → create_upload，PUT 字节，调用 remove_background(file)，然后轮询并返回透明 PNG。
• “为我的应用制作 UGC 广告” → generate_ugc(brief={...})，然后轮询 get_ugc_job_status。

有关状态值、预设键、操作参数和字段结构，请参阅 reference.md。

专项技能

此技能涵盖全部功能。若任务完全属于以下某项，专项技能能提供更深入的说明：

技能	涵盖内容	需要订阅
openclip-clipping	将长视频转换为按排名排列的病毒式片段	是
openclip-captions	为片段烧录样式化字幕	是
openclip-repurpose	将长视频端到端转换为可直接发布的一组内容	是
openclip-ugc-ads	根据简介制作 UGC 风格广告片段	否，每天免费 1 次
openclip-video-editing	修剪、裁剪、调整大小、旋转、压缩、静音	否
openclip-transcription	转录文本、SRT、VTT、说话人分离	否
openclip-convert	mp4、webm、mov、mkv、gif、mp3、aac、wav、flac	否
openclip-thumbnails	提取视频帧，以及图片编辑	否
openclip-remove-background	透明 PNG 抠图	否

使用 npx skills add OpenClip-App/agent-skills 安装其中任意技能。