ADD_IMAGES API 接口文档

接口信息

POST /openapi/capcut-tools/v1/add_images

功能描述

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

更多文档 📖 更多详细文档和教程请访问：https://docs.agent-ai-tools.com

请求参数

{
  "draft_url": "https://agent.aigc-ai.com/openapi/capcut-tools/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
}

参数说明

参数名 类型 必填 默认值 说明
draft_url string ✅ - 目标草稿的完整 URL
image_infos string ✅ - 图片信息数组的 JSON 字符串
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 数组结构

字段名 类型 必填 默认值 说明
image_url string ✅ - 图片文件的 URL 地址
width number ✅ - 图片宽度(像素)
height number ✅ - 图片高度(像素)
start number ✅ - 图片开始显示时间(微秒)
end number ✅ - 图片结束显示时间(微秒)

参数详解

时间参数

透明度参数

缩放参数

位置参数

图片信息说明

响应格式

成功响应 (200)

{
  "draft_url": "https://agent.aigc-ai.com/openapi/capcut-tools/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
    }
  ]
}

响应字段说明

字段名 类型 说明
draft_url string 更新后的草稿 URL
track_id string 视频轨道 ID
image_ids array 图片 ID 列表
segment_ids array 片段 ID 列表
segment_infos array 片段信息列表，包含每个片段的 ID、开始时间和结束时间

错误响应 (4xx/5xx)

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

使用示例

cURL 示例

1. 基本图片添加

curl -X POST https://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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 参数 提供有效的 draft_url
400 image_infos 是必填项 缺少图片信息参数 提供有效的 image_infos
400 image_url 是必填项 图片 URL 缺失 为每个图片提供 URL
400 图片尺寸无效 width 或 height 无效 提供正数的宽度和高度
400 时间范围无效 end 必须大于 start 确保结束时间大于开始时间
400 透明度无效 alpha 超出建议范围 使用 0.0-1.0 范围内的透明度值
404 草稿不存在 指定的草稿 URL 无效 检查草稿 URL 是否正确
404 图片不存在 指定的图片 URL 无效 确保图片 URL 正确
500 图片添加失败 内部处理错误 联系技术支持

注意事项

  1. 时间单位: 所有时间参数使用微秒（1 秒 = 1,000,000 微秒）
  2. 图片 URL: 确保使用有效的图片 URL
  3. 时间范围: end 必须大于 start
  4. 透明度范围: alpha 建议在 0.0-1.0 范围内
  5. 位置参数: transform_x 和 transform_y 为像素值，最终会转换为画布相对位置
  6. transform_x 转换公式：实际值 / 960（假设画布宽度 1920）
  7. transform_y 转换公式：实际值 / 540（假设画布高度 1080）
  8. 轨道管理: 系统会自动创建视频轨道
  9. 性能建议: 避免同时添加大量图片

工作流程

  1. 验证必填参数（draft_url, image_infos）
  2. 检查时间范围有效性
  3. 异步下载草稿
  4. 创建视频轨道（图片作为 VideoSegment）
  5. 创建图片资源设置
  6. 创建图片片段
  7. 添加片段到轨道
  8. 保存草稿
  9. 返回图片信息

相关接口