---
url: /docs/easy_create_material.zh.md
---
# EASY\_CREATE\_MATERIAL API 接口文档

## 🌐 语言切换

[中文版](/docs/easy_create_material.zh) | [English](/docs/easy_create_material)

## 接口信息

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

## 功能描述

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

## 请求参数

```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 秒时长（音频实际更短时取实际时长）
  * 添加到音频轨道
  * 支持多种音频格式

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

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

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

## 响应格式

### 成功响应 (200)

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

### 响应字段说明

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

### 错误响应

```json
{
  "code": 2028,
  "message": "素材创建失败"
}
```

## 使用示例

### 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"
  }'
```

## 错误码说明

| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 1001 | 参数校验失败 | `draft_url` 或 `audio_url` 缺失，或素材 URL 不是以 `http://` / `https://` 开头 | 检查参数类型与必填字段 |
| 2001 | 无效的草稿URL | `draft_url` 缺少 `draft_id`，或草稿不在缓存中 | 传入 `create_draft` 返回的 `draft_url` |
| 2028 | 素材创建失败 | 写入草稿过程出错 | 检查草稿状态与素材 URL 后重试 |
| 2042 | 草稿锁获取超时 | 同一草稿正在被其他操作占用（超时 30 秒） | 稍后重试 |

## 注意事项

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

## 工作流程

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

## 相关接口

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

***

📚 **项目资源**\
**GitHub**: <https://github.com/Hommy-master/capcut-mate>\
**Gitee**: <https://gitee.com/taohongmin-gitee/capcut-mate>