ReelQL Skill 技能

技能简介

ReelQL 是一个给 Agent 装上"眼睛"的视频理解技能：你贴进任意一个视频链接，它回给你一份带类型的 JSON 文档，里面包含摘要、章节划分、场景、出镜人物、关键瞬间、情绪曲线、出现的产品与品牌、画面上的文字以及完整转写文本。它的定位非常明确——"Agent 能读，但不能看"：TypeSafe 的 Jev 判断模型只读文本，官方建议先把视频转成文本或结构化字段，ReelQL 就是这一步。先由 ReelQL 观看视频并产出结构化结果，再由 Jev 把"看到的内容"变成你代码可以分支判断的决策。

核心能力

• 链接进、JSON 出：粘贴视频链接，返回一份包含摘要、章节、场景、cast、关键瞬间、情绪弧线、品牌与产品、on-screen 文字、完整 transcript 的结构化文档。
• 每个字段带时间戳：所有关键信息都保留时间点，方便后续按时间定位与剪辑引用。
• 与 Jev 判断配对：把 ReelQL 的字段喂给 Jev，提出有界的问题（是否与 brief 相符、是否品牌安全、哪个瞬间最合适），拿回的是概率而非需要解析的自然语言。
• 代码可直接决策：拿到真实数值后，排序、过滤、路由或标记都可用代码完成，例如把五条品牌短视频按 brief 排序（演示中 Samsung 77% 胜出、Nat Geo 6% 垫底）。
• 内置多种现成配方：品牌安全检测、brief 匹配度、剪辑点挑选、批量排序、素材投放核对等，都给出了输入字段与对应 Jev 问题的组合方式。
• 多客户端可用：Claude Code 以插件形式安装；claude.ai（Team / Enterprise）上传 reelql.zip 并配置允许域名；其他 Agent 直接走 HTTP API 或 SSH。

安装配置

• 第一步拿 Key（一次调用、无需注册，新 Key 附赠 10 分钟免费视频额度）：

curl -s -X POST https://reelql.tail6c0e2d.ts.net/keys
# {"key": "rql_...", "account": "k-...", "minutes": 10.0, ...}

• Claude Code 安装技能：

claude plugin marketplace add tomascupr/reelql
claude plugin install reelql@reelql
export REELQL_API_KEY=
export TYPESAFE_API_KEY=   # 可选，来自 console.typesafe.ai，启用排序与判断

• claude.ai（Team 与 Enterprise）：下载 reelql.zip，在 Settings → Capabilities → Skills 上传，Claude 询问时粘贴 Key；组织管理员需先把 reelql.tail6c0e2d.ts.net 加入代码执行允许域名。Pro 与 Max 的沙箱只能访问包仓库，请改用 Claude Code。
• 其他 Agent 或纯 curl：

API=https://reelql.tail6c0e2d.ts.net; H="X-API-Key: $REELQL_API_KEY"
curl -s -H "$H" -H 'Content-Type: application/json' $API/jobs -d '{"url": "https://www.youtube.com/watch?v=..."}'
# {"id": "6b0550c3dc9f", "status": "queued"}
curl -s -H "$H" $API/jobs/6b0550c3dc9f   # queued → running → done(带 result) 或 failed(带 error)

• 速度与计费：4 分钟视频约 25 秒、15 分钟约 1 分钟；按 $0.05/分钟从预付额度扣费，任务失败不收费，GET /balance 查看剩余分钟，额度不足会返回 402。

使用步骤

1. 用一次 POST 调用 /keys 自助生成 API Key（无需注册），拿到 rql_ 开头的密钥。
2. 按你的宿主环境完成安装：Claude Code 走插件市场，claude.ai 上传技能包，其他环境直接调用 HTTP 接口。
3. 在对话里贴链接并描述需求，例如"分析这个视频 "得到简版摘要，或"产品第一次出现在什么时候？"这类精确问题。
4. 需要判断时，把 Jev 也接上（设置 TYPESAFE_API_KEY），让技能把每条链接跑过 ReelQL 后再用捆绑的 scripts/jev.py 提五个问题（是否符合 brief、钩子、产品是否在用、情绪回报、是否含不安全内容）。
5. 在自己代码里复用同一套结果，例如按 summary、story.tone、brands、key_moments、transcript 组织 state，调用 Jev 的 Noul / Score / Choice 拿回可分支的数值。
6. 按需充值：浏览器内用 POST /credits/checkout {"usd": 5} 拿 Stripe 付款页，或在 Agent 内用 POST /credits {"usd": 5} 走 MPP（机器支付协议）。

适用场景

• 品牌安全审核：对广告或达人内容做逐项风险检查，并对严重度打分，把不合规素材拦在投放前。
• 创意 brief 匹配：判断视频是否"与 brief 相符"，并给出匹配度分数，辅助选片。
• 批量素材排序：一次跑多条视频，按钩子强度、产品呈现清晰度、情绪回报等维度打分后在代码里排序。
• 剪辑点挑选：从 key_moments 与场景里选出最符合需求的片段，作为二次剪辑或二创的起点。
• 投放核对：核对产品实际出现位置与转写中的宣称是否被证据支撑。
• 视频内容检索与摘要：为长视频生成结构化章节与时间戳摘要，方便做知识库或内容索引。

适用人群

• 做投放、内容营销与品牌安全审核的市场与运营团队。
• 需要给 Agent 增加视频理解能力的 AI 应用开发者。
• 短视频批量处理、素材二创与影视剪辑相关的创作者与创作者工具团队。
• 需要按 brief 筛选大量视频素材的 MCN 与代理公司。

工作原理

ReelQL 承担"看"的部分：接收视频链接后由服务端解码与理解，产出带时间戳的类型化 JSON（schema 版本 1.2），覆盖摘要、章节、场景、cast、关键瞬间、情绪弧线、品牌产品、画面文字与完整转写。Jev（TypeSafe 的判断模型）承担"判断"的部分：它只读文本，因此正好消费 ReelQL 输出的字段，按你定义的有界问题返回概率。最后一步由你的代码完成：在真实数值上排序、过滤、路由或标记。官方建议只把问题真正需要的字段送给 Jev（长视频的完整转写可能超出 Jev 上下文），而浏览量、点赞数等数值比较应放在代码里做。

官方链接

• GitHub 仓库：https://github.com/tomascupr/reelql
• 示例输出：仓库内 examples/（五条品牌 TikTok 的完整结果与 Jev 排序）
• TypeSafe / Jev 文档：https://docs.typesafe.ai