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. 返回圖片信息

相關接口

• 創建草稿
• 添加視頻
• 添加音頻
• 添加貼紙
• 保存草稿
• 生成視頻

📚 項目資源
GitHub: https://github.com/Hommy-master/capcut-mate
Gitee: https://gitee.com/taohongmin-gitee/capcut-mate