video-create/.claude/skills/capcut/references/api-reference.md

# CapCut Mate API 完整参数参考

所有接口基础 URL：`config.capcutMateApiBase`（如 `http://capcut.muyetools.cn/openapi/capcut-mate/v1`）
时间单位：**微秒**（1秒 = 1,000,000）
`xxx_infos` 参数均为 **JSON 字符串**（需 `JSON.stringify`）

---

## 目录

- [一、草稿管理](#一草稿管理)
- [二、视频素材](#二视频素材)
- [三、音频处理](#三音频处理)
- [四、文本字幕](#四文本字幕)
- [五、特效与动画](#五特效与动画)
- [六、视频渲染](#六视频渲染)
- [七、快速工具](#七快速工具)

---

## 一、草稿管理

### create_draft

```json
// POST /create_draft
{ "width": 1080, "height": 1920 }

// Response
{
  "draft_url": "http://capcut.muyetools.cn/openapi/capcut-mate/v1/get_draft?draft_id=20251230xxx",
  "tip_url": ""
}
```

### save_draft

```json
// POST /save_draft
{ "draft_url": "..." }

// Response
{ "draft_url": "...", "message": "成功" }
```

### get_draft

```json
// GET /get_draft?draft_id=xxx
// Response: 返回草稿文件列表和详细信息
```

---

## 二、视频素材

### add_videos

```json
// POST /add_videos
{
  "draft_url": "...",
  "video_infos": "[{\"video_url\":\"https://...\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":3000000,\"duration\":6000000,\"mask\":\"\",\"transition\":\"\",\"transition_duration\":500000,\"volume\":1}]",
  "alpha": 1,
  "scale_x": 1,
  "scale_y": 1,
  "transform_x": 0,
  "transform_y": 0,
  "scene_timelines": []
}

// Response
{
  "draft_url": "...",
  "video_ids": ["9b9f47126f384a6f95434cdc3fed5b7c"],
  "segment_ids": ["20285056b4194e2c8944b587ceb592a7"],
  "track_id": "720274203a11442280b64570caf362c4"
}
```

**全局参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| draft_url | string | 是 | 草稿 URL |
| video_infos | string(JSON) | 是 | 视频信息数组（JSON 字符串） |
| alpha | number | 否 | 透明度 0-1，默认 1 |
| scale_x | number | 否 | 水平缩放，默认 1 |
| scale_y | number | 否 | 垂直缩放，默认 1 |
| transform_x | number | 否 | 水平位移，默认 0 |
| transform_y | number | 否 | 垂直位移，默认 0 |

**video_infos 元素字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| video_url | string | 视频 URL |
| width | number | 宽度（像素） |
| height | number | 高度（像素） |
| start | number | 起始时间（微秒） |
| end | number | 结束时间（微秒） |
| duration | number | 总时长（微秒） |
| mask | string | 遮罩名称 |
| transition | string | 转场名称 |
| transition_duration | number | 转场时长（微秒） |
| volume | number | 音量 0-1 |

### add_images

```json
// POST /add_images
{
  "draft_url": "...",
  "image_infos": "[{\"image_url\":\"https://...\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000,\"duration\":5000000,\"animation\":\"淡入淡出\",\"transition\":\"溶解\",\"transition_duration\":500000}]",
  "alpha": 1,
  "scale_x": 1,
  "scale_y": 1,
  "transform_x": 0,
  "transform_y": 0
}

// Response
{
  "draft_url": "...",
  "image_ids": ["fa67760440104ca3adacdfd694fc25da"],
  "segment_ids": ["2d19f38d5f544eecad18847e5eac1745"],
  "segment_infos": [{"id": "xxx", "start": 0, "end": 5000000}],
  "track_id": "38c8dfee92374137998715329494a8f9"
}
```

**image_infos 元素字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| image_url | string | 图片 URL |
| width | number | 宽度（像素） |
| height | number | 高度（像素） |
| start | number | 起始时间（微秒） |
| end | number | 结束时间（微秒） |
| duration | number | 展示时长（微秒） |
| animation | string | 动画名称（如 "淡入淡出"） |
| transition | string | 转场名称（如 "溶解"） |
| transition_duration | number | 转场时长（微秒） |

### add_sticker

```json
// POST /add_sticker
{
  "draft_url": "...",
  "sticker_id": "7326810673609018675",
  "start": 0,
  "end": 5000000,
  "scale": 1,
  "transform_x": 0,
  "transform_y": 0
}

// Response
{
  "draft_url": "...",
  "sticker_id": "7326810673609018675",
  "segment_id": "7902e009fcfb44768f6f73e9432b5d5b",
  "track_id": "10b612824bcd4dd882ab764d145dd7ce",
  "duration": 5000000
}
```

---

## 三、音频处理

### add_audios

```json
// POST /add_audios
{
  "draft_url": "...",
  "audio_infos": "[{\"audio_url\":\"https://...\",\"duration\":23184000,\"end\":23184000,\"start\":0}]"
}

// Response
{
  "draft_url": "...",
  "audio_ids": ["9000bc9efb744c3196fb1d225993f43d"],
  "track_id": "a2d21e5a343c4f1eba3c9234bea16658"
}
```

**audio_infos 元素字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| audio_url | string | 音频文件 URL |
| start | number | 起始时间（微秒） |
| end | number | 结束时间（微秒） |
| duration | number | 音频总时长（微秒） |

### get_audio_duration

```json
// POST /get_audio_duration
{ "mp3_url": "https://..." }

// Response
{ "duration": 284891429, "message": "成功" }
```

---

## 四、文本字幕

### add_captions

```json
// POST /add_captions
{
  "draft_url": "...",
  "captions": "[{\"start\":0,\"end\":10000000,\"text\":\"你好，剪映\",\"keyword\":\"好\",\"keyword_color\":\"#457616\",\"keyword_font_size\":15}]",
  "font_size": 15,
  "text_color": "#ffffff",
  "alignment": 1,
  "bold": false,
  "italic": false,
  "underline": false,
  "has_shadow": false,
  "letter_spacing": 0,
  "line_spacing": 0,
  "alpha": 1,
  "scale_x": 1,
  "scale_y": 1,
  "transform_x": 0,
  "transform_y": 0,
  "style_text": 0
}

// Response
{
  "draft_url": "...",
  "text_ids": ["52ae035e01584adf8d052533d83948ed"],
  "segment_ids": ["1b1102e3d2d14b9eabac064bbe64d2bf"],
  "segment_infos": [{"id": "xxx", "start": 0, "end": 10000000}],
  "track_id": "7ffdf0f7d67e4d8caff5531f5873d26f"
}
```

**captions 元素字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| start | number | 起始时间（微秒） |
| end | number | 结束时间（微秒） |
| text | string | 字幕文本 |
| keyword | string | 高亮关键词 |
| keyword_color | string | 关键词颜色（如 "#ff7100"） |
| keyword_font_size | number | 关键词字号 |

**全局样式参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| font_size | number | 字号 |
| text_color | string | 文字颜色 |
| alignment | number | 对齐（1=居中） |
| bold | boolean | 粗体 |
| italic | boolean | 斜体 |
| underline | boolean | 下划线 |
| has_shadow | boolean | 文字阴影 |
| letter_spacing | number | 字间距 |
| line_spacing | number | 行间距 |
| style_text | number | 样式模式 |

### add_text_style

```json
// POST /add_text_style
{
  "text": "快乐|顶级思维",
  "keyword": "五个快乐到死的顶级思维",
  "keyword_color": "#ff7100",
  "keyword_font_size": 15,
  "font_size": 15
}

// Response
{
  "text_style": "{\"text\":\"快乐|顶级思维\",\"styles\":[{\"fill\":{\"content\":{\"solid\":{\"color\":[1.0,1.0,1.0]}}},\"range\":[0,7],\"size\":15}]}"
}
```

---

## 五、特效与动画

### add_effects

```json
// POST /add_effects
{
  "draft_url": "...",
  "effect_infos": "[{\"effect_title\":\"录制边框 III\",\"start\":0,\"end\":5000000}]"
}

// Response
{
  "draft_url": "...",
  "effect_ids": ["34c70fba3619444fa897110b40b39386"],
  "segment_ids": ["23e0c0900c69427f82e44243183706c9"],
  "track_id": "2ffea3839d304f83ae29dadc43a18227"
}
```

**effect_infos 元素字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| effect_title | string | 特效名称（如 "录制边框 III"、"雪花"、"红包来了"） |
| start | number | 起始时间（微秒） |
| end | number | 结束时间（微秒） |

### add_filters

```json
// POST /add_filters
{
  "draft_url": "...",
  "filter_infos": "[{\"filter_title\":\"清透感\",\"start\":0,\"end\":5000000,\"intensity\":100.0}]"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| filter_title | string | 滤镜名称 |
| start | number | 起始时间（微秒） |
| end | number | 结束时间（微秒） |
| intensity | number | 强度 0-100 |

### add_keyframes

```json
// POST /add_keyframes
{
  "draft_url": "...",
  "keyframes": "[{\"segment_id\":\"e1933f126437421bb52abdc56f062266\",\"property\":\"KFTypePositionX\",\"offset\":0.5,\"value\":-0.1}]"
}

// Response
{ "draft_url": "..." }
```

**keyframes 元素字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| segment_id | string | 目标素材 segment ID |
| property | string | 动画属性 |
| offset | number | 关键帧位置（0-1，相对素材时长比例） |
| value | number | 属性值 |

**property 可选值：**

| 值 | 说明 |
|------|------|
| KFTypePositionX | 水平位移 |
| KFTypePositionY | 垂直位移 |
| KFTypeScaleX | 水平缩放 |
| KFTypeScaleY | 垂直缩放 |
| KFTypeRotation | 旋转角度 |

### add_masks

```json
// POST /add_masks
{
  "draft_url": "...",
  "name": "线性",
  "segment_ids": ["beb4adbea83d41d08021cf4e8f219206"]
}

// Response
{}
```

### get_effects — 获取特效列表

```json
// POST /get_effects
{ "mode": 0 }

// Response
{
  "effects": [
    { "effect_id": "1183068", "name": "1998", "has_params": true, "is_vip": false },
    ...
  ]
}
```

---

## 六、视频渲染

### gen_video

```json
// POST /gen_video
{
  "draft_url": "...",
  "apiKey": "559a84a5-a9e9-4ade-a26b-e80b732754d6"
}

// Response
{ "code": 0, "message": "视频生成任务已提交，请使用draft_url查询进度" }
```

### gen_video_status

```json
// POST /gen_video_status
{ "draft_url": "..." }

// Response
{
  "code": 0,
  "status": "failed",
  "progress": 0,
  "video_url": "",
  "error_message": "导出草稿失败: ...",
  "created_at": "2026-01-31T21:09:15.104249",
  "started_at": "2026-01-31T21:09:15.549183",
  "completed_at": "2026-01-31T21:10:10.398727"
}
```

**status 值：** `processing` / `success` / `failed`

---

## 七、快速工具

### easy_create_material — 一站式添加

```json
// POST /easy_create_material
{
  "draft_url": "...",
  "video_url": "https://...",
  "img_url": "https://...",
  "audio_url": "https://...",
  "text": "字幕内容",
  "text_color": "#ffffff",
  "font_size": 15,
  "text_transform_y": 0
}

// Response
{ "draft_url": "...", "message": "成功" }
```