# EASY_CREATE_MATERIAL API 接口文档

## 接口信息

```
POST /openapi/capcut-mate/v1/easy_create_material
```

## 功能描述

在现有草稿中添加多种类型的素材内容，包括音频、视频、图片和文字。该接口可以一次性向草稿添加多种媒体素材，自动处理素材的时长、尺寸等属性，并智能管理不同类型的媒体轨道。是视频创作的核心接口之一。

## 更多文档

📖 更多详细文档和教程请访问：[https://docs.jcaigc.cn](https://docs.jcaigc.cn)

## 请求参数

```json
{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "audio_url": "https://assets.jcaigc.cn/audio.mp3",
  "text": "Hello World",
  "img_url": "https://s.coze.cn/t/JTa5Ne6_liY/",
  "video_url": "https://assets.jcaigc.cn/video.mp4",
  "text_color": "#ff0000",
  "font_size": 20,
  "text_transform_y": 100
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| audio_url | string | ✅ | - | 音频文件URL，不能为空或null |
| text | string | ❌ | null | 要添加的文字内容 |
| img_url | string | ❌ | null | 图片文件URL |
| video_url | string | ❌ | null | 视频文件URL |
| text_color | string | ❌ | "#ffffff" | 文字颜色（十六进制格式） |
| font_size | integer | ❌ | 15 | 字体大小 |
| text_transform_y | integer | ❌ | 0 | 文字Y轴位置偏移 |

### 参数详解

#### 必填参数

- **draft_url**: 目标草稿的完整URL
  - 格式：必须是有效的剪映草稿URL
  - 示例：`"https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"`

- **audio_url**: 音频文件URL
  - 必填参数，不能为空或"null"
  - 支持格式：MP3, WAV, AAC等常见音频格式
  - 说明：音频是必填参数，其他素材类型都是可选的

#### 可选参数

- **text**: 要添加的文字内容
  - 类型：UTF-8文本
  - 默认值：null（不添加文字）
  - 说明：如果提供，将添加文字素材到草稿中

- **img_url**: 图片文件URL
  - 类型：有效的图片URL
  - 默认值：null（不添加图片）
  - 支持格式：JPEG, PNG, GIF等常见图片格式
  - 说明：如果提供，将添加图片素材到草稿中

- **video_url**: 视频文件URL
  - 类型：有效的视频URL
  - 默认值：null（不添加视频）
  - 支持格式：MP4, AVI, MOV等常见视频格式
  - 说明：如果提供，将添加视频素材到草稿中

- **text_color**: 文字颜色
  - 类型：十六进制颜色代码
  - 默认值：`"#ffffff"`（白色）
  - 说明：设置文字颜色，使用标准十六进制格式（如 #ffffff、#000000）

- **font_size**: 字体大小
  - 类型：整数
  - 默认值：15
  - 说明：设置文字字体大小，建议范围10-50

- **text_transform_y**: 文字Y轴位置偏移
  - 类型：整数
  - 默认值：0
  - 说明：调整文字在画面中的垂直位置，单位为像素

#### 素材处理规则

- **音频处理**：
  - 自动解析音频时长
  - 添加到音频轨道
  - 支持多种音频格式

- **视频处理**：
  - 固定显示时长5秒
  - 保持原始分辨率比例
  - 添加到视频轨道

- **图片处理**：
  - 默认显示时长3秒
  - 自动获取图片尺寸
  - 添加到图片轨道

- **文字处理**：
  - 默认显示时长5秒
  - 支持颜色和字体大小设置
  - 可调整垂直位置

## 响应格式

### 成功响应 (200)

```json
{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258"
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| draft_url | string | 更新后的草稿URL |

### 错误响应 (4xx/5xx)

```json
{
  "detail": "错误信息描述"
}
```

## 使用示例

### cURL 示例

#### 1. 添加所有类型素材

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/easy_create_material \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "audio_url": "https://assets.jcaigc.cn/audio.mp3",
    "text": "Hello World",
    "img_url": "https://s.coze.cn/t/JTa5Ne6_liY/",
    "video_url": "https://assets.jcaigc.cn/video.mp4",
    "text_color": "#ff0000",
    "font_size": 20,
    "text_transform_y": 100
  }'
```

#### 2. 仅添加音频和文字

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/easy_create_material \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "audio_url": "https://assets.jcaigc.cn/background_music.mp3",
    "text": "欢迎观看",
    "text_color": "#0066ff",
    "font_size": 18
  }'
```

#### 3. 最简请求（仅音频）

```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/easy_create_material \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "audio_url": "https://assets.jcaigc.cn/audio.wav"
  }'
```

## 错误码说明

| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | audio_url是必填项 | 缺少音频URL参数 | 提供有效的audio_url |
| 400 | 无效的草稿信息，请检查草稿参数是否正确 | 草稿参数校验失败 | 检查草稿参数是否符合要求 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 500 | 素材创建失败 | 内部处理错误 | 联系技术支持 |

## 注意事项

1. **音频必填**: audio_url是必填参数，不能为空或null
2. **素材URL**: 素材URL必须可公开访问，建议使用HTTPS协议
3. **文字颜色**: text_color使用标准十六进制格式（如 #ffffff、#000000）
4. **字体大小**: font_size建议范围10-50
5. **位置偏移**: text_transform_y用于调整文字在画面中的垂直位置
6. **时长设置**: 不同素材类型有不同的默认显示时长
   - 音频：自动获取原始时长
   - 视频：固定5秒
   - 图片：默认3秒
   - 文字：默认5秒
7. **轨道管理**: 系统自动创建不同类型素材的轨道
8. **性能考虑**: 避免同时添加大量素材

## 工作流程

1. 验证必填参数（draft_url, audio_url）
2. 从缓存中获取草稿
3. 创建音频轨道并添加音频素材
4. 如果提供，创建视频轨道并添加视频素材
5. 如果提供，创建图片轨道并添加图片素材
6. 如果提供，创建文字轨道并添加文字素材
7. 保存草稿
8. 返回更新后的草稿URL

## 相关接口

- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加图片](./add_images.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)

---

<div align="right">

📚 **项目资源**  
**GitHub**: [https://github.com/Hommy-master/capcut-mate](https://github.com/Hommy-master/capcut-mate)  
**Gitee**: [https://gitee.com/taohongmin-gitee/capcut-mate](https://gitee.com/taohongmin-gitee/capcut-mate)

</div>