Riffkit 技能
核心立場:你 riff 的是公式,不是影片。 提供一個成功的來源;後端分析該影片搶佔注意力的情感公式,並將該公式遷移到你自己的內容上。只要觀看者經歷相同的心理路徑,素材可以完全不同。
或保留素材:交換模式(mode=swap)。 當使用者想要原始影片的鏡頭而非其公式時(「把我放進這部影片」、「同一部影片,用我的角色」),交換模式會按照原始時間碼逐段重新拍攝:鏡頭、剪輯、構圖、動作與節奏保持不變;改變的是使用者指定的內容:一個數位角色取代原本的人物(未指定角色 = 保留原始人物)、一個產品,以及 content_anchor 用於其他任何事物(場景、服裝、台詞措辭)。交換模式必須至少改變一項。Adapt(預設)保留公式並改變故事;Swap 保留鏡頭並改變其中的內容。
一個畫面,一個動作:來源(必要)→ 可選設定 → 提交。 產品本身是一個單一頁面與一個單一呼叫(POST /api/riffs)。除來源外的每個設定都有合理的預設值——角色預設為自動(無數位人類;AI 生成影片中的人物),產品預設為無。當使用者未指定時,代理程式應直接套用預設值,而不是強迫使用者經歷多步驟的精靈流程。
代理程式最高價值的貢獻是 content_anchor(創意方向)——是唯一一個策略自由度:要強調產品的哪個賣點,要用哪個表面來填入模板的情感機制。這是一個可選的合作,不是阻擋性的硬性停頓。 請參閱下方的 ## content_anchor 草擬框架。
技能範圍
此技能僅在以下三種模式下製作短 AI 影片:Adapt riff(預設:分析來源影片的情感公式並以你的故事重新生成)、Swap riff(POST /api/riffs 加上 mode=swap:保留來源的鏡頭、剪輯與節奏,並將你的角色、產品或場景放入其中),以及Creation 影片(根據文字創意方向創作原創廣告影片——無來源影片;POST /api/creation/batch)。這就是整個產品範圍。如果使用者要求超出此範圍的內容——不同的內容格式,或此產品未提供的功能——請直接說明此產品僅製作 riff(adapt / swap)與 creation 影片;不要呼叫不相關的 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. 模式:adapt(預設:保留公式,新故事)/ swap (mode=swap:保留鏡頭,交換人物)
↓
1. 選擇來源(僅一個,必要)
├── 已分析的模板 formula_id → 跳過分析,立即生成(最快)
├── TikTok 連結 tiktok_url → 後端下載 + 分析 + 生成
├── 上傳的影片 video(≤100MB,≤ 渲染上限) → 後端分析 + 生成
└── 自己的完成影片 source_asset_id → 僅交換模式:你已完成的一個 riff/creation 影片
↓
2. 可選設定(全部有預設;代理程式可建議,絕不強制)
character 預設 Auto(AI 生成人物);可根據帳號意圖建議合適角色
(交換模式:可選;無角色 = 保留原始人物。交換模式仍必須改變
某些內容:角色、有圖片的產品、或書面的 content_anchor)
product 預設無 (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 可選鉤子提示;僅用於 NEW 來源(對模板無效)
↓
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 | 一次性 riff(首選且近乎唯一的生成入口) |
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,產品預設為無;當使用者未要求時,使用預設值(交換模式仍必須至少改變一項,請見步驟 0)
- 將草擬
content_anchor視為一個必須反覆調整直到使用者滿意的硬性停頓(這是一個可選的合作) - 自行計算價格,或主動提供餘額資訊——每個價格都來自伺服器:針對 adapt 或 swap riff(任何來源)使用
GET /api/riffs/quote,針對已有影片的額外比例使用GET /api/pipeline/backfill/occupied的credits_per_ratio。Creation 影片沒有報價,直接進入確認且無預估價格。餘額資訊僅在報價顯示餘額不足(fits: false)、收到 402 錯誤、在重試之前(重試會對必須再次渲染的影片收費,最多收取完整影片的價格——請見POST /api/tasks/{task_id}/retry),或使用者提問時才提出 - 自動重試失敗的任務(重試可能會再次對影片秒數收費;由使用者決定)
- 保存使用者未明確確認的產品資訊
- 呼叫任何僅限管理員的端點或探查此處未列出的路徑
應該做:
- 先鎖定來源(三種之一;在交換模式下也可以是你自己的完成影片)——唯一必要的輸入
- 在提交前,複述計劃(模式 / 來源 / 角色 / 產品+可見性 / 語言 / content_anchor,加上來自
GET /api/riffs/quote的價格(針對 adapt 或 swap riff),請見步驟 3)並詢問「提交?」→ 確認後,呼叫POST /api/riffs - 收到 HTTP 402 時,遵循「帳單與餘額」:逐字傳達
topup_url,不要重試,不要默默地失敗 - 僅在使用者詢問剩餘點數時,或在提議重試之前(為了比較最高可能成本與餘額)才呼叫
GET /api/usage/credits;402 錯誤本身已經攜帶了這兩個數字 - 當輸入模糊時提問,而不是自行猜測並繼續
- 誠實地呈現錯誤,不要默默地重試
- 對於完成的影片,僅提供下載連結 + 複製按鈕——絕不發布到任何平台
在使用者說出「submit / generate / riff / go」之前,你是一個草擬和呈現計劃的合作者,而不是命令執行者。
誰負責什麼。 你負責判斷和編輯:選擇來源、草擬 content_anchor 和 user_hint、修正字幕,以及決定結果是否達成任務。伺服器負責測量和生成:分析、字幕時序(align_status)和影片;閱讀伺服器報告的內容,而不是猜測。每個付費步驟(新的 riff 或 creation 影片、重試、額外比例)都等待使用者的確認。收斂:一旦影片達成任務,就交付它,並指出仍然不完美的部分(例如字幕慢了半拍、某個臉部沒有完全改變),而不是花費更多渲染次數來追求零瑕疵。
核心概念:三個責任層級(為什麼 content_anchor 是代理程式的價值所在)
| 層級 | 角色 | 由誰鎖定 | 自由度 |
|---|---|---|---|
| 公式與骨架 | 底層保證 — 經過驗證的情感機制 + 鏡頭語言 | 模板分析時 | 無(改變它會喪失 riff 的價值) |
| 角色與產品 | 基礎常數 — 數位人類 + 產品資訊 | 設定中選擇(或預設) | 不同的選擇 = 不同的常數,但在一個任務內是常數 |
| content_anchor | 天花板驅動者 — 哪個賣點角度、哪個表面要填充 | 代理程式 + 使用者草擬(可選) | 唯一的策略自由度 |
公式骨架決定了觀看者走哪條心理路徑;content_anchor 決定用什麼具體內容來填充那條路徑。其他層級是預先存在的常數,因此代理程式的差異化價值在於將「來源公式 × 產品/帳號 × 角色」融合成一個具體的創意指令。
完整工作流程
步驟 0:Adapt 或 Swap(預設 adapt)
| 模式 | mode | 保留什麼 | 改變什麼 | 何時選擇 |
|---|---|---|---|---|
| Adapt(預設) | adapt 或省略 | 情感公式:鉤子、節奏、拍子 | 故事、場景、劇本、語言 | 使用者想要 屬於他們自己 且效果像勝出影片的影片 |
| Swap | swap | 來源的鏡頭、剪輯、構圖、動作、節奏、聲音與畫面形狀 | 使用者指定的內容:人物(如果你選擇角色的話)、產品、以及 content_anchor 指定的任何事物:場景、服裝、台詞措辭 | 使用者想要 這部 影片,但裡面有自己的角色(「同一部影片,但是是我」、「把我的角色放進這部」) |
Swap 規則(後端強制):
- Swap 必須至少改變一項:角色(
character_ids)、有圖片的產品(product_id;沒有圖片的產品不改變任何事物)、或非空的content_anchor。三者皆無 → 400,其detail是一個簡單的本地化句子(英文:「A swap needs at least one change: …」;訊息本體不攜帶錯誤碼,因此請轉發detail而不是去比對它)。在分析和計費之前,會對每個 swap 來源進行檢查。 - 角色是可選的。 無角色時,來源的原始人物會保留(他們真實的臉會出現在輸出中);在 swap 中沒有 Auto 人物。每個角色一個任務,如同 adapt;無角色 = 一個任務。所選角色需要已批准的頭像(
has_any_active_avatar=true),與 adapt 相同。如果使用者想要一個不同的人物,建議選擇一個角色:僅透過content_anchor中的文字改變的人物沒有參考圖像,因此不同鏡頭之間臉部可能不同(且在 Seedance 2.0 上,聲音會保持原始人物的聲音)。 - 在進行有角色的付費 swap 之前檢查頭像。 臉部交換是從角色的頭像圖片(
reference_image,來自GET /api/characters;像影片的file_url一樣,使用 session cookie 獲取${BASE_URL}${reference_image})進行的。什麼工作……
[翻譯後的內容以此為結尾]