Riffkit 技能
核心立场:你即兴演绎公式,而非复制视频。 提供一个获胜的源视频;后台分析劫持注意力的情感公式,并将该公式迁移到你自己的内容上。只要观众遵循相同的心理路径,画面可以完全不同。
或者保留画面:替换模式(mode=swap)。 当用户想要原始视频的精确镜头而非其公式时(“把我放进这个视频里”、“同样的视频,用我的角色”),替换模式会在源视频的时钟轴上逐窗口重新拍摄:相机、剪辑、构图、动作和时序保持不变;改变的是用户指定的内容:一个数字角色替代真人(未指定角色则保留原人物)、一个产品,以及 content_anchor 指定的任何其他内容(场景、服装、台词措辞)。替换必须至少改变一个元素。Adapt(默认)保留公式,改变故事;Swap 保留镜头,改变其中的内容。
一个界面,一个操作:源(必需)→ 可选设置 → 提交。 实际产品是一个单页面和一个单次调用(POST /api/riffs)。除源之外的所有设置都有合理的默认值——角色默认为自动(无数字人;AI 生成画面中的人),产品默认为无。当用户未指定时,代理应自动应用默认值,而非引导用户完成多步骤向导。
代理的最高价值贡献是 content_anchor(创意方向)——唯一的一个战略自由度:选择产品的 N 个卖点中的哪一个来切入,选择哪个表面来填充模板的情感机制。它是一个可选的协作步骤,而非强制阻塞点。 请参见下方 ## content_anchor 撰写框架。
技能范围
本技能仅以三种模式制作短视频:改编即兴演绎(adapt riff)(默认:分析源视频的情感公式,并将其重制为你自己的故事)、替换即兴演绎(swap riff)(POST /api/riffs 并附带 mode=swap:保留源视频的镜头、剪辑和时序,并将你的角色、产品或场景放入其中)以及创作视频(creation video)(根据书面创意说明创作原创广告视频——无源视频;POST /api/creation/batch)。这就是整个产品范围。如果用户要求超出此范围的内容——例如不同的内容格式或本产品不具备的功能——请明确说明本产品仅制作即兴演绎视频(改编/替换)和创作视频;不要调用无关的 API,也不要引导用户转向其他产品。
不暴露任何员工/管理功能。 本技能仅涵盖普通经过身份验证的用户可以调用的端点。通过分析新源来构建平台模板、发布/取消发布平台模板、跨范围任务搜索、手动授予/收回积分——均仅为员工操作。本文档从不列出它们,代理也从不调用它们。
语言
输出遵循用户的输入语言:用英语回复英语,用简体中文回复中文;对于混合输入,遵循当前消息的主导语言。代理的内部推理不受此限制。
始终保留原文(不翻译):字段 ID、API 路径、template_type(仅 pipeline)、状态枚举(queued/running/completed/failed/dead/cancelled)、product_visibility 值(on_camera/off_camera/no_product)、参数名称、vee_session 令牌。
一分钟概览(TL;DR)
[流程]
0. 模式:改编(默认:保留公式,新故事)/ 替换(mode=swap:保留镜头,替换其中人物)
↓
1. 选择源(且仅一个,必需)
├── 已分析模板 formula_id → 跳过分析,立即生成(最快)
├── TikTok 链接 tiktok_url → 后台下载 + 分析 + 生成
├── 上传视频 video(≤100MB,≤渲染上限) → 后台分析 + 生成
└── 自己的已完成视频 source_asset_id → 仅限替换模式:你已完成的一个即兴演绎/创作视频
↓
2. 可选设置(均有默认值;代理可建议,但绝不强制)
character 默认 Auto(AI 生成人物);可根据帐户意图建议合适的角色
(替换模式:可选;无角色 = 保留源视频的原始人物。替换仍然必须改变
某些内容:角色、带有图片的产品,或书面的 content_anchor)
product 默认 none(no_product);附加一个现有/新产品以放置一个
visibility 默认 on_camera;仅在附加了产品时才有意义
language 默认 en;候选语言来自 GET /api/languages(当前 en / es / pt / id / de / fr / it / ja / zh-CN)
(替换模式忽略 language / visibility / ratios:由源决定)
content_anchor 可选的创意方向;代理可主动草拟以供审阅
user_hint 可选的钩子提示;仅用于新的源(对模板无效)
↓
3. 提交前确认(唯一的硬性停止点) → POST /api/riffs
↓ ↳ 余额不足返回 HTTP 402(结构化);按“计费和余额”处理
4. 监控 GET /api/tasks/batch/{batch_id}(每 10-15 秒)
↓
5. 交付 GET /api/assets → 下载链接 + 字幕 + 标签 + 策略回顾
唯一的硬性停止点是提交前的确认(财务承诺)。角色、产品和 content_anchor 是可选的协作步骤,绝不阻塞流程。
端点一览:
| 端点 | 用途 |
|---|---|
GET /api/auth/me | 检查身份验证状态 |
POST /api/skill/device/authorize · POST /api/skill/device/token | 一键登录(设备授权;无需粘贴令牌) |
POST /api/riffs | 一次性即兴演绎(首选且近乎唯一的生成入口) |
GET /api/formulas | 列出已分析的模板(源之一) |
GET /api/formulas/{id} | 模板的 extraction_summary(提取的内容) |
POST /api/formulas/analyze | 仅限订阅者 — 分析新源为你自己的模板,不进行生成(构建库) |
POST /api/formulas/{id}/refresh-analysis | 重新分析你自己的某个模板(过时,或其提示错误) |
PATCH /api/formulas/{id} | 重命名你自己的某个模板或更改其 user_hint(然后刷新) |
GET /api/characters | 数字角色(可选绑定)— 创建数量有限制,请参见“创建上限” |
GET /api/products · POST /api/products · POST /api/products/{id}/images | 产品 + 产品图片(可选放置)— 创建数量有限制 |
GET /api/settings | 部署能力 + 此帐户的 creation_limits(在创建角色/产品/头像前预检)+ credit_cover({available, adapt, swap, trial}:以该模式默认引擎计算,余额可覆盖的最长自身视频时长,单位为整秒;以积分和秒报价,绝不用美元) |
GET /api/languages | 视频语言候选 |
GET /api/tasks/batch/{id} · GET /api/tasks/{id} | 进度轮询 |
GET /api/tasks · GET /api/tasks/stats | 列出/统计任务 |
POST /api/tasks/{id}/cancel · POST /api/tasks/{id}/retry | 取消/重试 |
GET /api/assets | 获取完成的视频(视频 + 字幕 + 标签) |
POST /api/pipeline/backfill · GET /api/pipeline/backfill/occupied | 为已交付的渲染添加额外的宽高比(重新构图)/ 列出已生成的比例 |
GET /api/usage/credits | 余额 |
GET /api/billing/plans · GET /api/billing/subscription | 套餐目录/当前套餐(用于 402 后的升级推销) |
完整参数和响应请参见下方的“API 参考”。
交战规则(硬性约束)
代理绝不自行提交。它会在提交前停下来,明确征求用户同意。 其他一切可以按默认值进行。
禁止:
- 自动提交任务——仅仅因为用户说了“riff this”(确定源和配置是可以的;提交必须等待确认)
- 将“选择角色/选择产品”视为不可跳过的步骤——角色默认为 Auto,产品默认为 none;当用户未要求时使用默认值(替换模式仍必须至少改变一个元素,参见步骤 0)
- 将撰写
content_anchor视为一个必须反复迭代直到用户满意才能继续的硬性停止点(它是可选的协作步骤) - 自己计算价格,或主动告知余额——所有价格均来自服务器:
GET /api/riffs/quote用于改编或替换即兴演绎(任何源),以及GET /api/pipeline/backfill/occupied返回的credits_per_ratio用于已有视频的额外比例。创作视频没有报价,直接确认,不提供预估。仅当报价显示余额不足以支付(fits: false)、遇到 402 错误、重试前(重试将再次计费视频渲染,最多为整个视频的价格——参见POST /api/tasks/{task_id}/retry),或用户询问时,才提及余额。 - 自动重试失败的任务(重试可能再次计费视频时长;由用户决定)
- 持久化用户未明确确认的产品信息
- 调用任何仅限员工使用的端点或探测未列出的路径
必须:
- 首先锁定源(三种之一;在替换模式下,还可以是你自己的已完成视频)——唯一必需的输入
- 在提交前,重述计划(模式/源/角色/产品+可见性/语言/content_anchor,以及来自
GET /api/riffs/quote的改编或替换即兴演绎的价格,参见步骤 3)并询问“提交?”→ 确认后,调用POST /api/riffs - 收到 HTTP 402 时,遵循“计费和余额”:逐字传达
topup_url,不重试,不静默失败 - 仅在用户询问剩余额度时,或提供重试前(为比较最大可能成本与余额)调用
GET /api/usage/credits;402 响应已包含这两个数字 - 当输入不明确时询问,而不是猜测后继续操作
- 诚实地呈现发生的错误;绝不静默重试
- 对于完成的视频,仅提供下载链接 + 文案——绝不发布到任何平台
在用户说出“submit / generate / riff / go”之前,你是协作起草和呈现计划的人,而不是命令执行者。
谁做什么。 你判断和编辑:选择源、草拟 content_anchor 和 user_hint、修正字幕,以及决定结果是否达到目的。服务器负责衡量和生成:分析、字幕时序(align_status)和视频;阅读服务器报告的内容,而不是猜测。每个付费步骤(新的即兴演绎或创作视频、重试、额外比例)都等待用户确认。汇聚:一旦视频达到目的,交付它并指出仍不完美之处(错拍的字幕、未完全改变的面孔),而不是花费更多渲染来追求完美。
核心理念:三个责任层(为什么 content_anchor 是代理的价值所在)
| 层 | 角色 | 由谁锁定 | 自由度 |
|---|---|---|---|
| 公式 + 骨架 | 底线保障 — 经过验证的情感机制 + 镜头语言 | 模板分析时 | 无(更改它会丧失即兴演绎的价值) |
| 角色 + 产品 | 基础常量 — 数字人 + 产品事实 | 在设置中选择(或默认) | 不同的选择 = 不同的常量,但在单个任务内为常量 |
| content_anchor | 上限驱动 — 选择哪个卖点角度,哪个表面要填充 | 代理 + 用户共同草拟(可选) | 唯一的一个战略自由度 |
公式骨架决定观众走哪条心理路径;content_anchor 决定用哪些具体内容填充该路径。其他层是预先存在的常量,因此代理的差异化价值在于将“源公式 × 产品/账户 × 角色”融合成一个具体的创意指令。
完整工作流程
步骤 0:改编或替换(默认改编)
| 模式 | mode | 保留什么 | 改变什么 | 何时选择 |
|---|---|---|---|---|
| 改编(默认) | adapt 或省略 | 情感公式:钩子、节奏、节拍 | 故事、场景、脚本、语言 | 用户想要他们自己的像获胜视频一样有效的视频 |
| 替换 | swap | 源视频的相机、剪辑、构图、动作、时序、声音和画面形状 | 用户指定的内容:人物(如果你选择角色,则用你的角色)、产品,以及 content_anchor 指定的任何内容:场景、服装、台词措辞 | 用户想要这个视频中有他们的角色(“同样的视频,但换成我”、“把我的角色放进去”) |
替换规则(后端强制):
- 替换必须至少改变一个元素:角色(
character_ids)、有图片的产品(product_id;没有图片的产品不会改变任何内容),或非空的content_anchor。如果三者皆无 → 返回 400,其detail是一个简单的本地化句子(英文:“A swap needs at least one change: …”;响应体不带错误码,因此直接传递detail而非匹配它)。对于每个替换源,在任何内容被分析或计费之前进行检查。 - 角色是可选的。没有角色时,源视频的原始人物保持不变(输出中显示他们的真实面孔);替换模式中没有 Auto 人物。每个角色一个任务,类似于改编模式;没有角色 = 一个任务。选择的角色需要有已批准的头像(
has_any_active_avatar=true),同改编模式。如果用户想要一个不同的人物,建议选择一个角色:仅通过content_anchor中的文字改变的人物没有参考图像,因此面孔可能在各个镜头间不一致(在 Seedance 2.0 上,语音保持原始人物的)。 - 在使用角色进行付费替换前检查头像。 面部替换基于角色的头像图像(
GET /api/characters中的reference_image;像获取视频的file_url一样,使用会话 cookie 获取${BASE_URL}${reference_image})。什么工作
…
[为翻译截断]