ADD_VIDEOS API 接口文檔

接口信息

POST /openapi/capcut-mate/v1/add_videos

功能描述

批量向現有草稿中添加視頻素材。該接口是一個功能強大的視頻添加工具，支持多個視頻的批量處理，包括時間範圍控制、透明度調整、遮罩效果、轉場動畫、音量控制、縮放變換等高級功能。特別適合創建複雜的多視頻組合場景，如畫中畫效果、視頻拼接、過渡動畫等。

更多文檔

📖 更多詳細文檔和教程請訪問：https://docs.jcaigc.cn

請求參數

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "video_infos": "[{\"video_url\":\"https://xxx/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":5000000,\"mask\":\"圓形\",\"transition\":\"淡入淡出\",\"transition_duration\":500000,\"volume\":0.8}]",
  "alpha": 0.5,
  "scale_x": 1.0,
  "scale_y": 1.0,
  "transform_x": 100,
  "transform_y": 200
}

參數説明

參數名 類型 必填 默認值 説明
draft_url string ✅ - 目標草稿的完整URL
video_infos string ✅ - 視頻信息數組的JSON字符串
alpha number ❌ 1.0 全局透明度(0-1)
scale_x number ❌ 1.0 X軸縮放比例
scale_y number ❌ 1.0 Y軸縮放比例
transform_x number ❌ X軸位置偏移(像素)
transform_y number ❌ Y軸位置偏移(像素)

video_infos 數組結構

字段名 類型 必填 默認值 説明
video_url string ✅ - 視頻文件的URL地址
width number ❌ - 視頻寬度(像素)，不傳則自動獲取視頻文件尺寸
height number ❌ - 視頻高度(像素)，不傳則自動獲取視頻文件尺寸
start number ✅ - 視頻開始播放時間(微秒)
end number ✅ - 視頻結束播放時間(微秒)
duration number ❌ end-start 視頻總時長(微秒)
mask string ❌ - 遮罩類型
transition string ❌ - 轉場效果名稱
transition_duration number ❌ 500000 轉場持續時間(微秒)
volume number ❌ 1.0 音量大小(0-1)

參數詳解

時間參數
  • start: 視頻在時間軸上的開始時間，單位微秒（1秒 = 1,000,000微秒）
  • end: 視頻在時間軸上的結束時間，單位微秒
  • duration: 視頻文件的總時長，用於素材創建（可選參數，如果不傳則默認為end-start）
  • 播放時長: 實際播放時長 = end - start
透明度參數
  • alpha: 全局透明度，應用於所有添加的視頻
    • 1.0 = 完全不透明
    • 0.5 = 半透明
    • 0.0 = 完全透明
    • 範圍：0.0 - 1.0
縮放參數
  • scale_x/scale_y: X/Y軸方向的縮放比例
  • 1.0 = 原始大小，0.5 = 縮小一半，2.0 = 放大兩倍
  • 建議範圍：0.1 - 5.0
位置參數
  • transform_x/transform_y: X/Y軸方向的位置偏移，單位像素
  • 正值向右/下移動，負值向左/上移動
  • 以畫布中心為原點
遮罩類型

支持的遮罩類型：

  • 圓形 - 圓形遮罩效果
  • 愛心 - 愛心形狀遮罩
  • 星形 - 星形遮罩
  • 矩形 - 矩形遮罩
  • 線性 - 線性漸變遮罩
  • 鏡面 - 鏡面反射遮罩
轉場效果
  • transition: 轉場效果名稱
  • transition_duration: 轉場持續時間
    • 最小值：100,000微秒（0.1秒）
    • 最大值：2,500,000微秒（2.5秒）
    • 推薦值：500,000微秒（0.5秒）
音量控制
  • volume: 視頻音量大小
    • 1.0 = 原始音量
    • 0.5 = 一半音量
    • 0.0 = 靜音
    • 範圍：0.0 - 1.0

響應格式

成功響應 (200)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "track_id": "video-track-uuid",
  "video_ids": ["video1-uuid", "video2-uuid", "video3-uuid"],
  "segment_ids": ["segment1-uuid", "segment2-uuid", "segment3-uuid"]
}

響應字段説明

字段名 類型 説明
draft_url string 更新後的草稿URL
track_id string 視頻軌道ID
video_ids array 添加的視頻ID列表
segment_ids array 片段ID列表

使用示例

cURL 示例

1. 基本視頻添加
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://xxx/video1.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000,\"duration\":10000000}]"
  }'
2. 多視頻批量添加
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://xxx/video1.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":5000000,\"duration\":10000000},{\"video_url\":\"https://xxx/video2.mp4\",\"width\":1280,\"height\":720,\"start\":5000000,\"end\":10000000,\"duration\":8000000}]",
    "alpha": 0.8
  }'
3. 帶遮罩和轉場的視頻
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://xxx/video1.mp4\",\"width\":1024,\"height\":1024,\"start\":0,\"end\":5000000,\"duration\":10000000,\"mask\":\"圓形\",\"transition\":\"淡入淡出\",\"transition_duration\":500000,\"volume\":0.8}]",
    "alpha": 1.0,
    "scale_x": 1.2,
    "scale_y": 1.2
  }'
4. 畫中畫效果
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_videos \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "video_infos": "[{\"video_url\":\"https://xxx/main.mp4\",\"width\":1920,\"height\":1080,\"start\":0,\"end\":10000000,\"duration\":15000000},{\"video_url\":\"https://xxx/pip.mp4\",\"width\":640,\"height\":360,\"start\":2000000,\"end\":8000000,\"duration\":10000000}]",
    "transform_x": 300,
    "transform_y": -200,
    "scale_x": 0.3,
    "scale_y": 0.3
  }'

錯誤碼説明

錯誤碼 錯誤信息 説明 解決方案
400 draft_url是必填項 缺少草稿URL參數 提供有效的草稿URL
400 video_infos是必填項 缺少視頻信息參數 提供有效的視頻信息JSON
400 video_infos格式錯誤 JSON格式不正確 檢查JSON字符串格式
400 video_url是必填項 視頻URL缺失 為每個視頻提供URL
400 視頻尺寸無效 width或height無效 提供正數的寬度和高度
400 時間範圍無效 end必須大於start 確保結束時間大於開始時間
400 透明度值無效 alpha不在0-1範圍內 使用0-1之間的透明度值
404 草稿不存在 指定的草稿URL無效 檢查草稿URL是否正確
404 視頻資源不存在 視頻URL無法訪問 檢查視頻URL是否可訪問
500 視頻處理失敗 內部處理錯誤 聯繫技術支持

注意事項

  1. JSON格式: video_infos必須是合法的JSON字符串
  2. 時間單位: 所有時間參數使用微秒（1秒 = 1,000,000微秒）
  3. 視頻格式: 確保視頻文件格式被支持（如MP4、AVI等）
  4. 文件大小: 大視頻文件可能影響處理速度
  5. 網絡訪問: 視頻URL必須可以正常訪問
  6. 遮罩限制: 只支持預定義的遮罩類型
  7. 轉場限制: 轉場時長有固定範圍限制
  8. 性能考慮: 批量添加大量視頻可能影響性能

工作流程

  1. 驗證必填參數（draft_url, video_infos）
  2. 解析video_infos JSON字符串
  3. 驗證每個視頻的參數配置
  4. 獲取並解密草稿內容
  5. 創建視頻軌道
  6. 添加視頻片段到軌道
  7. 應用透明度、縮放和位置變換
  8. 添加遮罩和轉場效果
  9. 設置音量
  10. 保存並加密草稿
  11. 返回處理結果

相關接口

  • 創建草稿
  • 添加音頻
  • 添加圖片
  • 保存草稿
  • 生成視頻

📚 項目資源
GitHub: 搜索capcut-mate即可找到