openclaw-voc-skill/dist/skills/quickly-video-create/SKILL.md

---

name: quickly-video-create description: 基于图片/视频素材一键生成短视频。传入素材URL列表和关键词，返回task_id，通过quickly-video-query轮询获取视频下载链接。

version: 1.1.0

一键成片 — 任务创建 (Quickly Video Create)

技能目的

将用户提供的图片/视频素材提交给 Quickly AI，异步生成短视频。返回 task_id 供下游轮询。

调用链（Workflow）

前置: 用户提供产品图片/视频素材
  ↓
Step 1: 素材预处理（格式转换 + 上传国内CDN）
  ↓
Step 2: quickly-video-create(material_list, tags) → task_id
  ↓
Step 3: quickly-video-query(task_id) → 轮询结果（每15秒，最多40次）
  ↓
Step 4: 返回 videoUrl / coverUrl 给用户
  ↓
可选: quickly-video-library → 查看历史视频库

输入参数

参数	类型	必填	说明
material_list	array	✅	素材列表，每项 { type: 'pic'\|'video', value: '公网URL' }，建议 5~15 个
tags	string	✅	逗号分隔关键词，描述视频主题，如 推拉门,极简风格,铝合金
proportion	string	✅	视频比例: 9:16(竖屏) / 3:4(竖屏宽) / 1:1(方形)
video_duration	object	✅	时长范围 { min: 10, max: 20 }，min: 5/10/15/20/25，max: 10/15/20/25/30
pre_id	string	✅	预定视频ID，纯数字 Date.now().toString()，多个用逗号分隔
compose_number	integer	❌	生成数量，默认1，最大50
ai_voice	0|1	❌	AI 配音，默认1
ai_bgm	0|1	❌	AI 背景音乐，默认1
ai_flower	0|1	❌	AI 特效，默认1
ai_subtitle	0|1	❌	AI 字幕，默认0
original_voice	0|1	❌	保留原始音频，默认0

以下参数已预置，Agent 无需传入：account_id、callback_url、appKey、appSecret

执行流程

1. 素材预处理（Agent 负责）

   • 确认图片格式为 jpg/jpeg/png/gif，视频为 mp4/webm
   • Quickly 不支持的格式（webp/heic/bmp/mov）→ 下载后转换并重新上传CDN
   • URL 含非 ASCII 字符 → 下载后重新上传 CDN 获取干净 URL
   • 确保 URL 在国内可达（使用 file-cloud.fmode.cn 或 file-cloud-qn.fmode.cn）
   • 建议：用 Canvas/System.Drawing 重编码为 baseline JPEG (quality=0.9)

2. 生成签名

   timestamp = Date.now().toString()
   sign = MD5(timestamp + '#' + appSecret).toLowerCase()   // 32位小写hex
   

3. 提交任务（通过中转服务）

   POST https://server.fmode.cn/api/functions/cut/onemerge
   Content-Type: application/json
   Body: { "action": "relay", "relayData": "<JSON string>" }
   

   ⚠️ HTTP body 必须以 UTF-8 编码发送（tags 含中文，非 UTF-8 会导致静默失败）

4. 获取 task_id → 传入 quickly-video-query 轮询

5. 轮询结果 → 调用 quickly-video-query(task_id)，每15秒一次，最多40次（约10分钟）

6. 返回视频 → 将 videoUrl / coverUrl 返回给用户

调用的底层 Skill

• quickly-video-query — 轮询视频生成结果（Step 5）
• quickly-video-library — 可选，查看历史视频库

返回格式

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "2039371716671352832"
  },
  "request_id": "abc123"
}

核心业务场景

• 商家「一键成片」：选择产品图片 → AI 自动生成短视频 → 发布到抖音/快手
• 批量视频生成：多组素材 + 不同关键词 → 批量提交，轮询获取结果
• 内容营销辅助：产品实景图 → 自动配音配乐 → 9:16 竖屏视频

素材要求速查

条件	要求	不满足时的处理
格式	jpg/jpeg/png/gif (图片), mp4/webm (视频)	转换后重新上传 CDN
URL 编码	纯 ASCII，无中文字符	重新上传 CDN 获取新 URL
可达性	国内 CDN 可直接访问	下载后上传到国内 CDN
图片质量	800~2000px，内容相关，清晰	重编码为 baseline JPEG
数量	建议 5~15 个素材	最少 1 个，效果随数量提升

注意事项

1. 🔴 UTF-8 编码：HTTP body 必须 UTF-8。Node.js/Python 默认支持；PowerShell 需 [System.Text.Encoding]::UTF8.GetBytes() 显式转换
2. 签名不解码：appKey 和 appSecret 均为原始字符串，不做 base64 解码
3. 静默失败：API 返回 task_id 不代表一定生成视频，需通过 query 轮询确认
4. 国内 CDN：素材 URL 必须国内可达，境外 CDN 会导致静默失败

依赖

• Quickly 开放平台账号（appKey/appSecret，已预置）
• server.fmode.cn 云函数中转（CORS + 回调接收）
• 国内公网可访问 CDN（如七牛 file-cloud.fmode.cn）