技能介绍

解决什么问题

在商品视频生成场景中，开发者常面临 API 接入复杂、参数配置繁琐、异步任务管理困难等问题。火山引擎创作Agent OpenAPI 虽提供视频生成能力，但原生接口需要手动处理提交、查询、取消等流程，且计费规则、模板选择、错误码解析等细节易导致开发成本上升。

技能如何工作

核心能力：封装三个官方接口（POST /openapi/ai_effect/submit、/query、/cancel），支持商品介绍视频（15/30/45/60秒）和主图视频（15/30秒）两类场景。通过 validate.py 实现提交前参数校验（模板ID、时长枚举、素材URL可达性），generate.py 自动完成提交-轮询-下载全流程，query_task.py 支持断点续查未完成任务。

关键步骤：

模板选择：提供4个预置模板（快速/专业模式 × 介绍/主图视频），明确展示创点消耗规则（如快速主图视频≤15秒仅0.21点）
素材管理：支持公网图片/视频URL输入，或通过抖店商品链接（product_url/product_id）自动拉取素材
参数校验：强制检查 duration 是否在模板允许的枚举值内（避免1418/1421错误），本地文件必须转为公网URL（否则触发1413错误）
费用透明：提交前通过 validate.py 输出预计创点消耗，需用户确认后才会执行 generate.py
结果回传：生成完成后自动下载MP4，通过本地预览页（preview.html + python -m http.server）实现对话框内嵌播放

适用边界与注意点

API Key 管理：社区版不内置任何密钥，需通过环境变量 KICKART_API_KEY 或 ~/.workbuddy/kickart_config.json 配置用户自有Key，避免密钥泄露风险
素材合规：本地文件必须上传至公网图床/对象存储获取URL，直接传本地路径会被服务端拒绝（错误码1413）
任务时效：视频生成通常耗时5-30分钟，最长1小时（超时返回1601错误码），result_url 仅24小时有效
错误处理：提供28个错误码速查表（如1404套餐权限、1413媒体URL无效、1601任务超时），支持通过 query_task.py --task-id 续查中断任务
合规要求：需确认素材授权（特别是人像素材），并同意《虚拟人像合规承诺函》与《合规承诺函》