---
name: capcut
description: 剪映/CapCut 自动化。通过 CapCut Mate API 实现草稿创建、素材导入、字幕添加、特效动画及云端渲染。支持两种模式：(1) API模式 — 单个接口调用；(2) 成片模式 — 素材目录一键组装（TTS配音+字幕+特效+BGM+云渲染）。触发词：剪映、CapCut、视频编辑、图片成片、视频合成、成片、CapCut组装、图片轮播、配音+成片。
---

# CapCut Mate 剪映自动化

通过 CapCut Mate API 自动化剪映草稿创建、素材导入及云端渲染。

## 前置条件

使用远程 CapCut Mate API（`config.capcutMateApiBase`），无需本地部署。
路径和密钥统一配置在 `skills/config.json`。

视频/音频素材通过 OSS 上传获取公网 URL（API 需要可下载的 URL）。
上传工具：`node .claude/skills/video-from-script/scripts/oss-upload.js`

**成片模式额外依赖：**

```
1. npm 依赖            → cd .claude/skills/video-from-script/scripts && npm install
2. TTS 配音            → 阿里云 CosyVoice TTS（config.json 中配置 ttsApiKey）
```

---

## 两种使用模式

### 模式一：API 模式（单接口调用）

用户给具体指令（加字幕、加特效等），Claude 直接调单个 API。

典型工作流：

```
1. create_draft(width, height) → draft_url
2. add_videos / add_images → 添加素材
3. add_audios → 添加配音/音乐
4. add_captions → 添加字幕（支持关键词高亮）
5. add_effects / add_keyframes → 特效和动画
6. save_draft → 保存
7. gen_video → 提交云端渲染
8. gen_video_status → 轮询进度
```

### 模式二：成片模式（一键组装）

用户给素材目录 + manifest.json，走 CLI 自动流水线。

```bash
node .claude/skills/video-from-script/scripts/capcut_assemble.js \
  --input ./output/batch_xxx \
  --manifest ./output/batch_xxx/manifest.json \
  --mode images|videos \
  --subtitles true \
  --bgm <url> \
  --effects "录制边框 III,雪花" \
  --filter "电影感:50" \
  --format 9:16 \
  --output ./output/final/
```

| 参数 | 必填 | 说明 |
|------|------|------|
| `--input` | 是 | 素材目录 |
| `--manifest` | 是 | manifest.json 路径 |
| `--mode` | 是 | `images` 或 `videos` |
| `--subtitles` | 否 | 字幕（默认 true） |
| `--bgm` | 否 | 背景音乐 URL |
| `--effects` | 否 | 特效，逗号分隔 |
| `--filter` | 否 | 滤镜名称:强度 |
| `--format` | 否 | 画幅（默认账号配置） |

**完整流程：**

```dot
digraph capcut_assembly {
  rankdir=LR
  node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]
  edge [fontsize=10]

  input [label="素材 + manifest.json", shape=folder, fillcolor="#e3f2fd"]

  step1 [label="1. TTS 配音（可选）\ncosyvoice → MP3 + 时长"]
  step2 [label="2. 上传图片到 OSS\n本地图片 → 公网 URL"]
  step3 [label="3. 创建草稿\ncreate_draft\n→ draft_url"]
  step4 [label="4. 导入素材+音频+字幕+特效\nadd_images / add_videos\nadd_audios / add_captions\nadd_effects"]
  step5 [label="5. 保存草稿\nsave_draft"]
  step6 [label="6. 同步本地剪映\nsync-to-jianying.js\n下载→重写→注册→扫描"]
  step7 [label="7. 云渲染（可选）\ngen_video → 成片 MP4", fillcolor="#e8f5e9"]

  input -> step1 -> step2 -> step3 -> step4 -> step5 -> step6 -> step7
}
```

**模式选择规则：**
- 用户提到"成片"、"组装"、"图片轮播"、"配音+成片" → 成片模式
- 用户给具体操作指令（加字幕、加特效等） → API 模式
- 不确定时 → 询问用户

---

## 通用约定

- **时间单位**: 微秒（1秒 = 1,000,000）
- **xxx_infos 参数**: JSON **字符串**（需 `JSON.stringify`），非对象
- **draft_url**: 创建草稿后返回，后续所有操作都需要传入

---

## 核心接口速查

| 接口 | 用途 | 关键参数 |
|------|------|----------|
| `create_draft` | 创建草稿 | width, height |
| `add_videos` | 添加视频 | video_infos (URL+时长+转场) |
| `add_images` | 添加图片 | image_infos (URL+动画+转场) |
| `add_audios` | 添加音频 | audio_infos (URL+时长) |
| `add_captions` | 添加字幕 | captions (文本+关键词高亮+时间线) |
| `add_effects` | 添加特效 | effect_infos (名称+时间线) |
| `add_keyframes` | 关键帧动画 | keyframes (segment_id+属性+值) |
| `easy_create_material` | 一站式添加 | video/img/audio/text |
| `gen_video` | 云端渲染 | draft_url + apiKey |

## 工具类接口

| 接口 | 入参 | 产出 |
|------|------|------|
| `audio_timelines` | `links: [mp3 URLs]` | 自动算时间线 |
| `audio_infos` | mp3_urls + timelines | add_audios 的 audio_infos |
| `caption_infos` | texts + timelines + keywords | add_captions 的 captions |
| `effect_infos` | effects[] + timelines | add_effects 的 effect_infos |
| `video_infos` | URLs + timelines | add_videos 的 video_infos |
| `imgs_infos` | URLs + timelines | add_images 的 image_infos |
| `get_audio_duration` | mp3_url | 音频时长（微秒） |
| `get_text_animations` | 无 | 可用文本动画列表 |
| `get_image_animations` | 无 | 可用图片动画列表 |
| `search_sticker` | 关键词 | 贴纸列表（含 sticker_id） |
| `get_url` | 文本 | 提取 URL |

## 完整 API 参数文档

详细的请求参数、响应格式、字段说明见 [api-reference.md](references/api-reference.md)

---

## TTS 配音（成片模式用）

使用阿里云 CosyVoice TTS（通过 DashScope WebSocket），Pipeline 自动调用。

```js
// 作为模块调用
const { synthesize } = require('./qwen-tts')
const { filePath, duration } = await synthesize('你好世界', { voice: 'Cherry' })
```

配置在 `skills/config.json`：`ttsApiKey`（必填）、`ttsModel`、`ttsVoice`、`ttsLanguage`。

推荐音色：

| 音色 | 风格 | 适用 |
|------|------|------|
| `Cherry` | 阳光积极小姐姐 | 通用、生活 |
| `Ethan` | 阳光温暖男声 | 科技、教程 |
| `Vincent` | 沙哑烟嗓 | 军事、纪录 |
| `Neil` | 新闻主持人 | 新闻、财经 |
| `Moon` | 率性帅气男声 | 解说、潮流 |

---

## 账号配置

`account.json` 中 CapCut 相关字段：

```json
{
  "capcut": {
    "effects": ["录制边框 III"],
    "filter": "电影感:40",
    "subtitleStyle": {
      "fontSize": 36,
      "color": "#FFFFFF",
      "highlightColor": "#FF6B35",
      "bold": true
    },
    "defaultBGM": "https://example.com/bgm.mp3"
  }
}
```

---

## 图片动画预设

| 动画名称 | 说明 | 适用 |
|------|------|------|
| 缩放 | 缓慢放大（默认） | 通用 |
| 渐显+放大 | 淡入+放大组合 | 强调 |
| 左平移 | 右→左平移 | 风景 |
| 右平移 | 左→右平移 | 风景 |

---

## 质量要求

- 字幕与文案对应正确
- 图片动画流畅
- BGM 音量不盖过配音（配音为主、BGM 为辅）
- 转场自然（无黑帧、无跳帧）
- 底部字幕区不被遮挡
- 总时长 30-90 秒（保证完播率）
- 9:16 竖屏适配抖音/快手，16:9 横屏适配 B 站

---

## 成片模式详细参考

完整步骤说明、API 调用细节见 [assembly-guide.md](references/assembly-guide.md)

## index.js 封装

当前 `index.js` 只封装了 3 个接口（createDraft, addVideos, genVideo）。
调用其他接口时，直接用 axios POST 对应的 API 路径即可。