opensource/capcut-mate
3
0
Fork 0
mirror of https://github.com/Hommy-master/capcut-mate.git synced 2026-08-28 23:27:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

优化文档。

Browse Source
This commit is contained in:
Hommy
2025-12-01 22:56:50 +08:00
parent d62a194b28
commit 9307bb6402
1 changed files with 106 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/add_images.md
+106 -196
View File
@@ -8,7 +8,7 @@ POST /openapi/capcut-mate/v1/add_images
## 功能描述
批量向现有草稿中添加图片素材。该接口支持多个图片的批量处理，包括透明度调整、缩放变换、位置偏移、动画效果等功能。在剪映系统中，图片被作为VideoSegment处理。
向现有草稿中添加图片。该接口用于在指定的时间段内添加图片素材到剪映草稿中，支持图片的透明度、缩放和位置调整。图片可以用于增强视频的视觉效果，如背景图、水印、装饰图等。
## 更多文档
@@ -19,7 +19,7 @@ POST /openapi/capcut-mate/v1/add_images
```json
{
"draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/image1.jpg\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000,\"duration\":5000000,\"animation\":\"淡入淡出\",\"transition\":\"溶解\",\"transition_duration\":500000}]",
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/image1.jpg\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000}]",
"alpha": 1.0,
"scale_x": 1.0,
"scale_y": 1.0,
@@ -28,17 +28,17 @@ POST /openapi/capcut-mate/v1/add_images
}
```
### 主要参数
### 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| draft_url | string | ✅ | - | 目标草稿的完整URL |
| image_infos | string | ✅ | - | 图片信息数组的JSON字符串 |
| alpha | number | ❌ | 1.0 | 全局透明度(0-1) |
| scale_x | number | ❌ | 1.0 | X轴缩放比例 |
| scale_y | number | ❌ | 1.0 | Y轴缩放比例 |
| transform_x | number | ❌ | 0 | X轴位置偏移(像素) |
| transform_y | number | ❌ | 0 | Y轴位置偏移(像素) |
| alpha | number | ❌ | 1.0 | 图片透明度，建议范围[0.0, 1.0] |
| scale_x | number | ❌ | 1.0 | 图片X轴缩放比例 |
| scale_y | number | ❌ | 1.0 | 图片Y轴缩放比例 |
| transform_x | number | ❌ | 0 | X轴位置偏移（像素） |
| transform_y | number | ❌ | 0 | Y轴位置偏移（像素） |
### image_infos 数组结构
@@ -49,27 +49,59 @@ POST /openapi/capcut-mate/v1/add_images
| height | number | ✅ | - | 图片高度(像素) |
| start | number | ✅ | - | 图片开始显示时间(微秒) |
| end | number | ✅ | - | 图片结束显示时间(微秒) |
| duration | number | ✅ | - | 图片显示总时长(微秒) |
| animation | string | ❌ | - | 动画效果名称 |
| transition | string | ❌ | - | 转场效果名称 |
| transition_duration | number | ❌ | 500000 | 转场持续时间(微秒) |
### 参数详解
#### 时间参数
- **start**: 图片开始显示时间，单位微秒（1秒 = 1,000,000微秒）
- **end**: 图片结束显示时间，单位微秒
- **duration**: 图片总显示时长，通常等于 end - start
#### 透明度和变换
- **alpha**: 全局透明度，范围0.0-1.0
- **scale_x/scale_y**: 缩放比例，1.0为原始大小
- **transform_x/transform_y**: 位置偏移，以画布中心为原点
- **start**: 图片在时间轴上的开始时间，单位为微秒（1秒 = 1,000,000微秒）
- **end**: 图片在时间轴上的结束时间，单位为微秒
- **duration**: 图片显示时长 = end - start
#### 动画和转场
- **animation**: 支持"淡入淡出"、"缩放入场"、"滑动入场"等
- **transition**: 转场效果名称
- **transition_duration**: 转场时长，范围100,000-2,500,000微秒
#### 透明度参数
- **alpha**: 图片的透明度
- 1.0 = 完全不透明
- 0.5 = 半透明
- 0.0 = 完全透明
- 建议范围：0.0 - 1.0
#### 缩放参数
- **scale_x**: 图片在X轴方向的缩放比例
- 1.0 = 原始大小
- 0.5 = 缩小到一半
- 2.0 = 放大到两倍
- **scale_y**: 图片在Y轴方向的缩放比例
- 1.0 = 原始大小
- 0.5 = 缩小到一半
- 2.0 = 放大到两倍
#### 位置参数
- **transform_x**: 图片在X轴方向的位置偏移，单位为像素
- 正值向右移动
- 负值向左移动
- 以画布中心为原点
- 实际存储时会转换为半画布宽单位（假设画布宽度1920，即除以960）
- **transform_y**: 图片在Y轴方向的位置偏移，单位为像素
- 正值向下移动
- 负值向上移动
- 以画布中心为原点
- 实际存储时会转换为半画布高单位（假设画布高度1080，即除以540）
#### 图片信息说明
- **image_url**: 图片的URL地址
- 格式：有效的图片URL
- 示例：`"https://assets.jcaigc.cn/image1.jpg"`
- 支持格式：JPG、PNG等常见图片格式
- **width/height**: 图片的原始尺寸
- 用于计算位置偏移的转换比例
- 单位：像素
## 响应格式
@@ -97,226 +129,104 @@ POST /openapi/capcut-mate/v1/add_images
|--------|------|------|
| draft_url | string | 更新后的草稿URL |
| track_id | string | 视频轨道ID |
| image_ids | array | 添加的图片ID列表 |
| image_ids | array | 图片ID列表 |
| segment_ids | array | 片段ID列表 |
| segment_infos | array | 片段详细信息列表 |
| segment_infos | array | 片段信息列表，包含每个片段的ID、开始时间和结束时间 |
### 错误响应 (4xx/5xx)
```json
{
"detail": "错误信息描述"
}
```
## 使用示例
### cURL 示例
#### 基本图片添加
#### 1. 基本图片添加
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/photo1.jpg\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000,\"duration\":5000000}]"
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/photo1.jpg\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000}]"
}'
```
#### 带动画效果的图片
#### 2. 带透明度的图片
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/logo.png\",\"width\":800,\"height\":600,\"start\":1000000,\"end\":4000000,\"duration\":3000000,\"animation\":\"缩放入场\",\"transition\":\"淡入淡出\"}]",
"alpha": 0.9,
"scale_x": 1.2,
"scale_y": 1.2,
"transform_x": 200,
"transform_y": -100
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/logo.png\",\"width\":800,\"height\":600,\"start\":1000000,\"end\":6000000}]",
"alpha": 0.8
}'
```
### JavaScript 示例
#### 3. 带缩放和位置偏移的图片
```javascript
const addImages = async (draftUrl, imageConfig) => {
const response = await fetch('/openapi/capcut-mate/v1/add_images', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
draft_url: draftUrl,
...imageConfig
})
});
return response.json();
};
// 基本图片添加
const basicImages = {
image_infos: JSON.stringify([
{
image_url: "https://assets.jcaigc.cn/cover.jpg",
width: 1920,
height: 1080,
start: 0,
end: 5000000,
duration: 5000000
}
])
};
// 图片幻灯片
const slideshow = {
image_infos: JSON.stringify([
{
image_url: "https://assets.jcaigc.cn/slide1.jpg",
width: 1920,
height: 1080,
start: 0,
end: 3000000,
duration: 3000000,
animation: "淡入淡出",
transition: "淡入淡出"
},
{
image_url: "https://assets.jcaigc.cn/slide2.jpg",
width: 1920,
height: 1080,
start: 3000000,
end: 6000000,
duration: 3000000,
animation: "滑动入场",
transition: "滑动"
}
])
};
// 图片水印
const watermark = {
image_infos: JSON.stringify([
{
image_url: "https://assets.jcaigc.cn/logo.png",
width: 300,
height: 100,
start: 0,
end: 30000000,
duration: 30000000,
animation: "淡入淡出"
}
]),
alpha: 0.7,
scale_x: 0.5,
scale_y: 0.5,
transform_x: 700,
transform_y: -400
};
try {
const result1 = await addImages(draftUrl, basicImages);
const result2 = await addImages(draftUrl, slideshow);
const result3 = await addImages(draftUrl, watermark);
console.log('图片添加成功');
} catch (error) {
console.error('添加失败:', error);
}
```
### Python 示例
```python
import requests
import json
class ImageProcessor:
def __init__(self, base_url="https://capcut-mate.jcaigc.cn"):
self.base_url = base_url
def add_images(self, draft_url: str, image_config: dict) -> dict:
response = requests.post(
f'{self.base_url}/openapi/capcut-mate/v1/add_images',
headers={'Content-Type': 'application/json'},
json={
"draft_url": draft_url,
**image_config
}
)
return response.json()
def create_slideshow(self, images: list, slide_duration: int = 3000000) -> dict:
"""创建幻灯片播放"""
current_time = 0
image_infos = []
for image in images:
image_info = {
"image_url": image["url"],
"width": image["width"],
"height": image["height"],
"start": current_time,
"end": current_time + slide_duration,
"duration": slide_duration,
"animation": image.get("animation", "淡入淡出")
}
image_infos.append(image_info)
current_time += slide_duration
return {"image_infos": json.dumps(image_infos)}
# 使用示例
processor = ImageProcessor()
slideshow_config = processor.create_slideshow([
{
"url": "https://assets.jcaigc.cn/slide1.jpg",
"width": 1920,
"height": 1080,
"animation": "淡入淡出"
}
])
result = processor.add_images("YOUR_DRAFT_URL", slideshow_config)
print(f"图片添加成功: {result['track_id']}")
```bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_images \
-H "Content-Type: application/json" \
-d '{
"draft_url": "YOUR_DRAFT_URL",
"image_infos": "[{\"image_url\":\"https://assets.jcaigc.cn/watermark.png\",\"width\":300,\"height\":100,\"start\":2000000,\"end\":7000000}]",
"scale_x": 0.5,
"scale_y": 0.5,
"transform_x": 700,
"transform_y": -400
}'
```
## 错误码说明
| 错误码 | 错误信息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 400 | draft_url是必填项 | 缺少草稿URL | 提供有效的草稿URL |
| 400 | image_infos是必填项 | 缺少图片信息 | 提供有效的图片信息JSON |
| 400 | image_infos格式错误 | JSON格式不正确 | 检查JSON字符串格式 |
| 400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
| 400 | image_infos是必填项 | 缺少图片信息参数 | 提供有效的image_infos |
| 400 | image_url是必填项 | 图片URL缺失 | 为每个图片提供URL |
| 400 | 图片尺寸无效 | width或height无效 | 提供正数的宽度和高度 |
| 400 | 时间范围无效 | end必须大于start | 确保结束时间大于开始时间 |
| 404 | 草稿不存在 | 草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 图片资源不存在 | 图片URL无法访问 | 检查图片URL是否可访问 |
| 500 | 图片处理失败 | 内部处理错误 | 联系技术支持 |
| 400 | 透明度无效 | alpha超出建议范围 | 使用0.0-1.0范围内的透明度值 |
| 404 | 草稿不存在 | 指定的草稿URL无效 | 检查草稿URL是否正确 |
| 404 | 图片不存在 | 指定的图片URL无效 | 确认图片URL是否正确 |
| 500 | 图片添加失败 | 内部处理错误 | 联系技术支持 |
## 注意事项
1. **JSON格式**: image_infos必须是合法的JSON字符串
2. **时间单位**: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
3. **图片格式**: 支持JPG、PNG、GIF等格式
4. **网络访问**: 图片URL必须可以正常访问
5. **透明度范围**: alpha值必须在0.0-1.0范围内
6. **图片处理**: 图片在剪映中作为VideoSegment处理
7. **动画效果**: 不是所有动画效果都兼容所有转场效果
1. **时间单位**: 所有时间参数使用微秒（1秒 = 1,000,000微秒）
2. **图片URL**: 确保使用有效的图片URL
3. **时间范围**: end必须大于start
4. **透明度范围**: alpha建议在0.0-1.0范围内
5. **位置参数**: transform_x和transform_y单位为像素，但内部会转换为半画布单位存储
- transform_x转换公式：实际值 / 960（假设画布宽度1920）
- transform_y转换公式：实际值 / 540（假设画布高度1080）
6. **轨道管理**: 系统自动创建视频轨道
7. **性能考虑**: 避免同时添加大量图片
## 工作流程
1. 验证必填参数（draft_url, image_infos）
2. 解析image_infos JSON字符串
3. 验证每个图片的参数配置
4. 获取并解密草稿内容
5. 创建视频轨道（图片作为VideoSegment）
6. 添加图片片段到轨道
7. 应用透明度、缩放和位置变换
8. 添加动画和转场效果
9. 保存并加密草稿
10. 返回处理结果
2. 检查时间范围的有效性
3. 从缓存中获取草稿
4. 创建视频轨道（图片作为VideoSegment）
5. 创建图像调节设置
6. 创建图片片段
7. 添加片段到轨道
8. 保存草稿
9. 返回图片信息
## 相关接口
- [创建草稿](./create_draft.md)
- [添加视频](./add_videos.md)
- [添加音频](./add_audios.md)
- [添加贴纸](./add_sticker.md)
- [保存草稿](./save_draft.md)
- [生成视频](./gen_video.md)