video-create/.claude/skills/capcut/references/assembly-guide.md

CapCut 成片组装

将图片/视频素材通过 CapCut 组装为成品视频。支持配音、字幕、特效、音乐、云渲染。

• 触发词: 图片成片、视频合成、剪映成片、CapCut 渲染

---

前置条件

1. CapCut Mate API 可达 → curl {config.capcutMateApiBase}/../docs
   - 部署在 capcut.muyetools.cn（配置在 skills/config.json）
2. npm 依赖            → cd scripts && npm install
3. TTS 配音            → 阿里云 CosyVoice TTS（配置在 config.json 的 ttsApiKey）
4. 同步到本地剪映       → 纯 Node.js（sync-to-jianying.js），无需 Python/uv

所有路径和 API 地址统一从 skills/config.json 读取。

---

CLI 接口（快速开始）

node 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	否	画幅（默认取账号配置）
--output	否	输出目录

---

完整流程

digraph assembly_flow {
  rankdir=LR
  node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]

  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 → draft_url"]
  step4 [label="4. 导入素材+音频+字幕+特效"]
  step5 [label="5. 保存草稿\nsave_draft"]
  step6 [label="6. 同步本地剪映\n下载→重写→注册→扫描"]
  step7 [label="7. 云渲染（可选）\ngen_video → 成片 MP4", fillcolor="#e8f5e9"]

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

---

详细步骤

1. TTS 配音（可选）

使用阿里云 CosyVoice TTS 进行语音合成（通过 DashScope WebSocket，Node.js）。

const { synthesize } = require('./qwen-tts')
const { filePath, duration } = await synthesize('文案', { voice: 'Neil', outputDir: './audio' })
// → ./audio/seg_001.mp3, duration: 3.456

配置在 skills/config.json：

字段	说明	默认值
ttsApiKey	阿里云百炼 API Key	（必填）
ttsModel	模型名称	cosyvoice-v3.5-plus
ttsVoice	音色名称	账号配置
ttsLanguage	语言类型	Chinese

推荐音色：

voice 参数	音色名	风格	适用
Cherry	芊悦	阳光积极小姐姐	通用、生活
Serena	苏瑶	温柔小姐姐	情感、故事
Ethan	晨煦	阳光温暖男声	科技、教程
Moon	月白	率性帅气男声	潮流、解说
Vincent	田叔	沙哑烟嗓男声	军事、纪录
Kai	凯	温柔磁性男声	情感、配音
Neil	阿闻	新闻主持人	新闻、财经
Bellona	燕铮莺	洪亮有力女声	热血、武侠

所有音色均支持中英文，输出 MP3 格式（24kHz）。

作为模块调用：

const { synthesize, synthesizeBatch } = require('./qwen-tts')

// 单段
const { filePath, duration } = await synthesize('你好世界', { voice: 'Cherry' })

// 批量
const results = await synthesizeBatch(
  [{ id: 1, text: '文案' }, { id: 2, text: '文案2' }],
  { voice: 'Cherry', outputDir: './audio' }
)

2. 图片上传

CapCut API 需要公网 URL，本地图片通过 OSS 上传：

node scripts/oss-upload.js ./image.png
# → https://i.ibb.co/xxx/image.png

OSS 配置在 skills/config.json 的 ossRegion/ossAccessKeyId/ossAccessKeySecret/ossBucket 中。

capcut_assemble.js 自动处理上传，无需手动调用。

3. 创建草稿

POST /create_draft  { width: 1080, height: 1920 }
→ 返回 draft_url（后续所有操作都需要传入）

4. 导入素材

图片模式 (--mode images):

POST /add_images
每张图片 3-5 秒，附带动画（默认缩放）

视频模式 (--mode videos):

POST /add_videos
逐个添加视频片段，自动计算时长

5. 添加音频

POST /add_audios
- BGM: 账号默认音乐 或 用户指定 URL
- 配音: Step 1 生成的 TTS 音频

6. 添加字幕

POST /add_captions
- 文案来自 manifest.json（TTS 分句时按 segment 精确对齐）
- 字体大小、颜色从账号配置读取

7. 添加特效/滤镜

POST /add_effects   ← account.json 中 capcut.effects
POST /add_filters   ← account.json 中 capcut.filter

8. 保存 + 同步 + 渲染

保存草稿（服务器端）：

POST /save_draft → 保存到 CapCut Mate 服务器

同步到本地剪映（纯 Node.js）：

sync-to-jianying.js → 下载素材文件 → 路径重写为本地 → 写入剪映草稿目录 → 注册 root_meta_info.json → 触发目录扫描

无需 Python/uv，capcut_assemble.js 自动调用。

504 超时回退：

add_videos 提交 9+ 视频时可能触发网关 504。脚本自动降级：

1. 先尝试全量提交
2. 504 时自动分批（每批 3 个），保持绝对时间不变

---

图片动画预设

动画名称	说明	适用场景
缩放	缓慢放大	默认，适合大多数场景
渐显+放大	淡入+放大组合	强调、冲击感
左平移	右→左平移	风景、全景
右平移	左→右平移	风景、全景

---

质量检查

• 字幕与文案对应正确
• 图片动画流畅（无卡顿）
• BGM 音量与配音平衡
• 转场自然（无黑帧）
• 总时长合理（建议 30-90 秒）