---
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` — 可选，查看历史视频库

## 返回格式
```json
{
  "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`）