《御灵宗》-创作Agent 爆款裂变 OpenAPI

基于火山引擎 创作Agent 爆款裂变 API 的官方接入 skill。忠实实现文档定义的三个接口： 提交异步任务、查询任务结果、取消任务。用于「复刻爆款视频结构，替换成自己的产品」场景。

📦 对外可分享版：本版不内置任何作者 API Key，进入生成前引导用户完成火山账号绑定并添加企业微信获取配置支持。用户使用自己的 Key 生成视频，额度消耗归用户自己的账号。

与 kickart-creator（本地文件上传版）的区别：本 skill 严格遵循官方 OpenAPI 文档， 所有素材（ref_video / product_images / model_images）均为公网 URL，不接受本地路径。 若用户只有本地文件，请先托管为可公网访问的 URL 再传入（见「本地素材处理」）。

⭐ 引导式执行流程（skill 的核心职责）

本 skill 不是一次性命令，而是「一步步带用户走完出片」的向导。 每次被触发，都按下面 6 步引导， 每步只问当前需要的信息，确认后再进入下一步，不要一次性把所有参数砸给用户。

第 0 步：一句话开场（不要啰嗦）

"我用爆款裂变 API 帮你把一段参考视频'翻拍'成带你自己产品的营销视频。需要你提供：①一段参考视频的公网链接 ②你的商品（抖店链接/商品ID/商品图 三选一）。其余参数我用默认值，边走边跟你确认。"

第 1 步：收集参考视频 ref_video（必填）

• 向用户要公网可访问的视频 URL（MP4/MOV，≤50MB，>5s 且 ≤60s，≥480p，比例 9:16/16:9/3:4/4:3/1:1）。
• 若用户给的是本地文件：明确告知"API 只认公网 URL，本地文件我没法直接提交"，请他先传到对象存储/图床拿 URL；或直接走第 2 步的抖店商品（平台自己拉素材，最省事）。
• 收到后复述一遍链接，确认可访问。

第 2 步：收集商品来源（三选一，必填其一）

• product_url：抖店商品链接（如 https://v.douyin.com/xxx/），链接前后不要有文字/空格。
• product_id：抖店商品 ID。
• product_images：商品图公网 URL 列表（0–10 张，JPEG/PNG，≤8MB，≥480p，宽高比 0.4–2.5）。
• 推荐优先用 product_url/product_id（平台自动拉素材）；没有抖店商品才用 product_images。

第 3 步：确认可选项（带默认值，用户可跳过）

• language：默认 zh（中文口播/字幕）。需其它语言再问。
• template_id：默认 208714754（专业模式，质量高耗时较长）；想快用 346374402（进阶模式）。
• model_images：模特参考图（≤3 张），不传=智能匹配。一般跳过。
• ai_product_analysis：默认开启；除非用户要求关闭。
• watermark：是否加"AI生成"明水印，默认不加。

第 4 步：组装参数并请用户确认

• 把收集到的参数写成工作区里的 test_input.json（键名同 CLI：template_id/ref_video/product_url/product_id/product_images/model_images/language/no_ai_analysis/watermark/output）。
• 用一张小表格把"即将提交的内容"复述给用户，等用户明确说"可以/提交吧"再动手。
• 例：

  参数	值
  模板	208714754 专业模式
  参考视频	https://...
  商品	product_url=https://...
  语言	zh

第 5 步：提交并轮询（后台运行）

• 调用 scripts/generate.py --input <工作区>/test_input.json --output <工作区>/viral_result.mp4 --poll-interval 15，用 run_in_background=true 启动（--max-wait 默认 3600=1 小时，与官方超时一致，不要设成几分钟，否则会误判超时）。
• 如果因为没有 API Key 生成不了（脚本报错"未找到 KICKART_API_KEY"），不要直接告诉用户失败了，而是进入「社区版生成引导」（见下方专门章节）：引导用户绑定火山账号 → 扫码加企微 → 配置自己的 Key → 再重新提交生成。
• 告知用户"已开始生成，通常 10–25 分钟，完成后我直接在对话框里放可播放的视频"。
• 用 TaskOutput 等待结果（生成一般 10–25 分钟，最长 1 小时；真机实测占位图素材约 16 分钟）。
• 若 generate.py 报本地超时（任务仍在服务端跑）：输出里会带 task_id，直接用 query_task.py --task-id --download --output <工作区>/viral_result.mp4 续跑下载，再用 preview.py 生成自包含预览 HTML 即可，不要重新提交。
• 若失败（非超时），按「错误码速查 / 故障排查」定位并反馈用户，必要时修复后重试。

第 6 步：内嵌播放回传（必须，对话框内展示）

• generate.py 成功后输出 result_url（火山引擎公网 https 直链，24h 有效）+ 本地 downloaded_file。
• 首选（已实测最稳）：用 present_files 直接打开 result_url → WorkBuddy 预览面板用浏览器内置播放器内嵌播放原视频。公网 https 直链，无 localhost、无 data URI、无中间服务，不会被环境回收。
• 兜底1：result_url 过期/不可达时，用 present_files 回传本地 viral_result.mp4 文件卡片（可下载/打开）。
• 兜底2（仅小视频 <5MB 且上述都不可用）：preview.py 生成自包含 HTML（base64 data URI）用 present_files 打开。⚠️ data URI 有大小限制，大视频（如 30MB+）会被浏览器拒绝加载，不可作主方案。
• ⚠️ 不再推荐：python -m http.server 本地服务（环境会回收进程）+ 大 data URI HTML（浏览器拒大文件）。
• 同时给用户一句话总结：消耗创点、task_id、保存路径，并提醒 result_url 24h 内有效、尽快保存。

不要只给一段文字结论或只发下载链接——产物必须在对话框里能直接播放，这是硬性要求。

回传保障（调用 skill 必读，绝不掉链子）

为避免"生成完了却不回传/不播放"，强制执行以下机制：

1. task_id 落盘：generate.py 提交成功后立刻把 task_id 写入 /last_task_id.txt。即便后台任务句柄丢失/会话中断，也能从这里恢复。
2. 查询自动重试：generate.py 轮询遇网络抖动(1500)自动重试不退出；提交遇网关超时自动重试 3 次。不会因瞬时网络问题整个垮掉。
3. 主动恢复，不只等通知：generate.py 后台跑后，不要只等 。合理时间（约 10–15 分钟）仍无结果，或后台句柄丢失/报错，立刻按下面恢复：
   • 读 <工作区>/viral_test/last_task_id.txt 拿 task_id；
   • query_task.py --task-id 查状态；code=0 → 拿 result_url；
   • 立刻 present_files(result_url) 内嵌播放回传（公网 https 直链，最稳）。
4. 必回传：无论正常完成还是异常恢复，只要拿到 result_url，必须 present_files(result_url) 在对话框内嵌播放；result_url 不可达才退回本地 mp4 文件卡片。绝不允许"生成了但不回传"。

兜底顺序：① present_files(result_url)（首选，公网直链内嵌播放）→ ② present_files(本地 mp4 文件卡片) → ③ 小视频(<5MB)自包含 HTML。

API 总览

凭证配置（社区版）

本 Skill 为社区可分享版，不内置任何作者 API Key。用户需自行绑定火山账号并配置自己的 API Key 后使用。

API Key 读取优先级：环境变量 KICKART_API_KEY > 用户级 ~/.workbuddy/kickart_config.json。

✅ 安全说明：本 Skill 文件夹内不含任何真实密钥，可安全分享给他人使用。

以下脚本命令仅当用户主动询问"怎么配置 Key"时才展示，普通说明中不要出现 bash 代码块或 Python 路径：

PY "C:/Users/zuoer/.workbuddy/skills/kickart-viral-openapi/scripts/setup_config.py" --set "新Key"

PY = managed Python：C:/Users/zuoer/.workbuddy/binaries/python/versions/3.13.12/python.exe

社区版生成引导

铁律：

• 必须直接把可点击的链接和二维码图片亮出来，不能用「我会引导你：1. 打开链接... 2. 扫码...」这种纯文字描述代替。
• 默认不要展示 bash 命令、脚本路径、Python 路径等技术细节，只给普通用户能看懂的操作说明。如果用户主动问"怎么配置 Key"，才提供脚本命令。

当用户到第 5 步尝试提交生成、因为没有 API Key 生成不了时，按以下干净格式直接展示：

生成前请先完成绑定

这个 skill 不内置 Key。开始生成前，如果你还没有配置自己的 API Key，请先完成火山账号绑定，并添加企业微信获取配置支持。完成后即可使用你自己的 Key 生成视频，额度消耗归你自己的账号。

1. [点此绑定火山账号](https://partner.volcengine.com/partner/invite/FXN6ICPAAMQ)
2. 扫码添加企业微信（二维码用 present_files 直接展示）
3. 配置你自己的 API Key 后继续生成

实际输出时：

• 第 1 步的链接必须直接渲染为可点击 markdown 链接
• 第 2 步必须直接 present_files 打开二维码图片（路径：C:/Users/zuoer/.workbuddy/skills/kickart-ai-effect-public/assets/template_media/community/community_wecom_qr.jpg），不要把文件路径当正文输出
• 第 3 步不要展开 bash 命令，只说"配置完 Key 后告诉我，我带你继续生成"

文案目标是"先亮链接和二维码让用户立即可操作"，不要写成"我会引导你完成绑定"这种描述性话术，也不要把脚本命令甩给普通用户。

模板说明（爆款裂变专用）

--template-id 默认 208714754（专业模式）；想用快速模式传 346374402。

payload 字段

顶层额外字段：callback_url（可选，任务完成 POST 回调，回调体同查询响应）、watermark（boolean，默认 false，视频右下角加"AI生成"明水印）。暗水印由 SaaS 后台配置自动生效，无需传入。

⚠️ 合规：调用须确认有权使用所提交信息及内容，承诺上传人像素材均为已授权虚拟人像，并同意《虚拟人像合规承诺函》与《合规承诺函》。

脚本用法

通用提交参数：--ref-video(必填) --product-url --product-id --product-images(多值) --model-images(多值,≤3) --language(默认zh) --no-ai-analysis(关闭AI分析) --callback-url --watermark(开关) --quiet(仅JSON) --template-id(默认208714754) --no-preview(只下载不起预览服务)。

generate.py 额外支持 --input （从文件读全部参数，测试/批量更方便）。

本地文件需先获取公网 URL 再传入；直接传本地路径会被服务端拒绝（错误码 1413）。

本地素材处理（用户只有本地文件时）

官方接口只收公网 URL，本 skill 不内置图床上传（避免国内网络下上传全失败）。两种稳妥方式：

1. 挂公网 URL：把文件传到对象存储/图床，拿到 URL 后传入。
2. 抖店商品：直接传 product_url 或 product_id，由平台拉取商品素材，无需自行托管图片。

响应与状态

提交响应：{"code":0,"data":{"task_id":"..."},"message":"success","request_id":"..."}（非 0 见错误码）。

查询响应：

• code=0 成功；data.payload.result_url 为结果视频地址；data.usage 为消耗创点。
• code=1000 运行中；data 仅含 task_id。
• 其它非 0 为失败。

⚠️ result_url 仅 24 小时有效，拿到后请尽快下载保存。

取消响应：code=0 取消成功 / 1602 已取消 / 1603 已结束不可取消 / 1604 取消失败稍后重试。

错误码速查

通用：1300 认证失败(API Key 无效/过期) · 1400 参数错误 · 1401 并发超限 · 1403 无权限(API/接口未开通) · 1402 创点不足 · 1418 无效时长参数 · 1423 参考视频分辨率错误 · 1424 参考视频时长错误 · 1425 参考视频格式错误 · 1426 参考视频大小错误 · 1427 参考视频链接错误 · 1500 内部错误 · 1404 账号未开通爆款裂变 combo 权限（联系商务/管理员开通）。

接口特定：

• 0 成功 · 1000 运行中 · 1410 模板不存在 · 1411 分辨率错误 · 1412 图片格式错误 · 1413 媒体URL无效(不可公网访问/过期) · 1414 输入内容安全拦截 · 1415 输出内容安全拦截 · 1416 媒体数量错误 · 1417 大模型调用错误 · 1421 时长枚举值错误 · 1422 抖店商品信息获取失败 · 1428 语言枚举值错误 · 1429 model_images 图片数量超出(>4) · 1600 任务不存在 · 1601 任务超时(1h) · 1602 已取消 · 1603 已结束 · 1604 取消失败 · 2000 任务失败 · 5000 工作流失败(底层兜底)。

完整文档见 references/api-doc.md。

故障排查