ADD_IMAGES API 接口文档

接口信息

POST /openapi/capcut-mate/v1/add_images

功能描述

向现有草稿中添加图片。该接口用于在指定的时间段内添加图片素材到剪映草稿中，支持图片的透明度、缩放和位置调整。图片可以用于增强视频的视觉效果，如背景图、水印、装饰图等。

更多文档

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

请求参数

{
   
  "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}]",
  "alpha": 1.0,
  "scale_x": 1.0,
  "scale_y": 1.0,
  "transform_x": 0,
  "transform_y": 0
}

参数说明

image_infos 数组结构

参数详解

时间参数

• start: 图片在时间轴上的开始时间，单位为微秒（1秒 = 1,000,000微秒）
• end: 图片在时间轴上的结束时间，单位为微秒
• duration: 图片显示时长 = end - start

透明度参数

• 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: 图片的原始尺寸

  • 用于计算位置偏移的转换比例
  • 单位：像素

响应格式

成功响应 (200)

{
   
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "track_id": "video-track-uuid",
  "image_ids": ["image1-uuid", "image2-uuid"],
  "segment_ids": ["segment1-uuid", "segment2-uuid"],
  "segment_infos": [
    {
   
      "id": "segment1-uuid",
      "start": 0,
      "end": 5000000
    }
  ]
}

响应字段说明

错误响应 (4xx/5xx)

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

使用示例

cURL 示例

1. 基本图片添加

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}]"
  }'

2. 带透明度的图片

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\":6000000}]",
    "alpha": 0.8
  }'

3. 带缩放和位置偏移的图片

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
  }'

错误码说明

注意事项

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. 检查时间范围的有效性
3. 从缓存中获取草稿
4. 创建视频轨道（图片作为VideoSegment）
5. 创建图像调节设置
6. 创建图片片段
7. 添加片段到轨道
8. 保存草稿
9. 返回图片信息

相关接口

• 创建草稿
• 添加视频
• 添加音频
• 添加贴纸
• 保存草稿
• 生成视频