AIVideoMaker API 执行器

用途

为 AIVideoMaker API v1 提供一套可用于生产环境的执行工作流：

• 创建生成任务
• 安全轮询任务状态
• 获取任务详情
• 取消已提交的任务

适用场景

• 用户要求直接调用 aivideomaker.ai 的 API
• 用户需要可脚本化的视频生成工作流
• 用户需对任务查询具备健壮的重试机制及 429 错误处理能力

必需运行环境

• AIVIDEO_API_KEY（必填）：请前往 https://aivideomaker.ai 获取 API 密钥。
• AIVIDEO_TIMEOUT_MS（选填，默认值 30000）：请求超时时间，单位为毫秒
• AIVIDEO_MAX_RETRIES（选填，默认值 3）：幂等读请求的最大重试次数

支持的操作

1. createGeneration
2. getTask
3. getStatus
4. cancelTask

模型白名单

• t2v
• i2v
• lv
• t2v_v3
• i2v_v3

图像输入策略

• 本技能支持公共图像 URL 和 data:image/...;base64,... 格式，适用于 i2v、lv 和 i2v_v3 模型。
• 在 OpenClaw 环境中，为保障可靠性，建议优先使用 data:image/...;base64,... 格式。

标准工作流

1. 依据契约校验模型类型与请求载荷（payload）。
2. 调用 createGeneration 创建任务。
3. 以指数退避策略轮询 getStatus，直至任务进入终态（terminal status）。
4. 若状态为 COMPLETED，调用 getTask 获取完整任务结果并返回输出。
5. 若状态为 FAILED，返回失败信息，并附带可操作的后续步骤建议。

错误处理策略

• 统一响应结构为：
  • ok、status、taskId、data、errorCode、errorMessage、retryAfter
• 将 API 层或运行时错误映射为稳定错误码：
  • INVALID_MODEL
  • INVALID_PAYLOAD
  • AUTH_FAILED
  • RATE_LIMITED
  • INSUFFICIENT_CREDITS
  • TASK_NOT_FOUND
  • NETWORK_ERROR
  • UNKNOWN_ERROR

执行命令

• 运行完整工作流：
  • node scripts/run-workflow.mjs --model --payload ''
• 查询任务状态：
  • node scripts/run-workflow.mjs --action getStatus --taskId
• 查询任务详情：
  • node scripts/run-workflow.mjs --action getTask --taskId
• 取消任务：
  • node scripts/run-workflow.mjs --action cancelTask --taskId

安全性

本技能仅执行以下操作：

• 使用用户提供的参数调用 AIVideoMaker API
• 依据预定义契约校验输入载荷（payload）
• 仅读取通过 --payload 参数传入的载荷内容
• 不读取任意主机文件、凭据或敏感系统信息
• 不执行任意代码或 Shell 命令

所有网络请求均发送至 https://aivideomaker.ai（或通过客户端配置项指定的自定义基础 URL），且仅包含用于身份验证的 API 密钥。该密钥作为 HTTP 请求头 key（AIVideoMaker API 所要求）发送。虽然 HTTPS 加密了传输过程，但中间代理仍可能记录 key 请求头。用户应意识到向上游服务发送图像数据和 API 密钥所涉及的隐私风险。

安全最佳实践：

• 切勿在源代码、配置文件或技能归档包中硬编码 API 密钥
• 始终通过环境变量传递 AIVIDEO_API_KEY
• 使用密钥管理工具或平台专用的凭据存储方案
• 定期轮换 API 密钥并监控其使用情况

其他资源

• 完整 API 接口矩阵：references/api-reference.md
• 使用示例与故障场景说明：references/examples.md