ADD_STICKER API 接口文檔

接口信息

POST /openapi/capcut-mate/v1/add_sticker

功能描述

向現有草稿中添加貼紙。該接口用於在指定的時間段內添加貼紙素材到剪映草稿中，支持貼紙的縮放和位置調整。貼紙可以用於增強視頻的視覺效果，如表情、裝飾、文字等。

更多文檔

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

請求參數

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "sticker_id": "7326810673609018675",
  "start": 0,
  "end": 5000000,
  "scale": 1.0,
  "transform_x": 0,
  "transform_y": 0
}

參數説明

參數名 類型 必填 默認值 説明
draft_url string ✅ - 目標草稿的完整URL
sticker_id string ✅ - 貼紙的唯一標識ID
start number ✅ - 貼紙開始時間（微秒）
end number ✅ - 貼紙結束時間（微秒）
scale number ❌ 1.0 貼紙縮放比例，建議範圍[0.1, 5.0]
transform_x number ❌ X軸位置偏移（像素）
transform_y number ❌ Y軸位置偏移（像素）

參數詳解

時間參數
  • start: 貼紙在時間軸上的開始時間，單位為微秒（1秒 = 1,000,000微秒）
  • end: 貼紙在時間軸上的結束時間，單位為微秒
  • duration: 貼紙顯示時長 = end - start
縮放參數
  • scale: 貼紙的縮放比例
    • 1.0 = 原始大小
    • 0.5 = 縮小到一半
    • 2.0 = 放大到兩倍
    • 建議範圍：0.1 - 5.0
位置參數

  • transform_x: 貼紙在X軸方向的位置偏移，單位為像素

    • 正值向右移動
    • 負值向左移動
    • 以畫布中心為原點
    • 實際存儲時會轉換為半畫布寬單位（假設畫布寬度1920，即除以960）

  • transform_y: 貼紙在Y軸方向的位置偏移，單位為像素

    • 正值向下移動
    • 負值向上移動
    • 以畫布中心為原點
    • 實際存儲時會轉換為半畫布高單位（假設畫布高度1080，即除以540）
貼紙ID説明
  • sticker_id: 貼紙的唯一標識符
    • 格式：通常為數字字符串
    • 示例："7326810673609018675"
    • 獲取方式：通過剪映貼紙庫或相關API獲取

響應格式

成功響應 (200)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "sticker_id": "7326810673609018675",
  "track_id": "track-uuid",
  "segment_id": "segment-uuid",
  "duration": 5000000
}

響應字段説明

字段名 類型 説明
draft_url string 更新後的草稿URL
sticker_id string 貼紙的唯一標識ID
track_id string 貼紙軌道ID
segment_id string 貼紙片段ID
duration number 貼紙顯示時長（微秒）

錯誤響應 (4xx/5xx)

{
  "detail": "錯誤信息描述"
}

使用示例

cURL 示例

1. 基本貼紙添加
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "sticker_id": "7326810673609018675",
    "start": 0,
    "end": 5000000
  }'
2. 帶縮放的貼紙
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "sticker_id": "7326810673609018675",
    "start": 1000000,
    "end": 6000000,
    "scale": 1.5
  }'
3. 帶位置偏移的貼紙
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_sticker \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "sticker_id": "7326810673609018675",
    "start": 2000000,
    "end": 7000000,
    "scale": 0.8,
    "transform_x": 200,
    "transform_y": -100
  }'

錯誤碼説明

錯誤碼 錯誤信息 説明 解決方案
400 draft_url是必填項 缺少草稿URL參數 提供有效的draft_url
400 sticker_id是必填項 缺少貼紙ID參數 提供有效的sticker_id
400 start是必填項 缺少開始時間參數 提供有效的start時間
400 end是必填項 缺少結束時間參數 提供有效的end時間
400 時間範圍無效 end必須大於start 確保結束時間大於開始時間
400 縮放比例無效 scale超出建議範圍 使用0.1-5.0範圍內的縮放值
400 無效的貼紙信息，請檢查貼紙參數是否正確 貼紙參數校驗失敗 檢查貼紙參數是否符合要求
404 草稿不存在 指定的草稿URL無效 檢查草稿URL是否正確
404 貼紙不存在 指定的貼紙ID無效 確認貼紙ID是否正確
500 貼紙添加失敗 內部處理錯誤 聯繫技術支持

注意事項

  1. 時間單位: 所有時間參數使用微秒（1秒 = 1,000,000微秒）
  2. 貼紙ID: 確保使用有效的貼紙ID
  3. 時間範圍: end必須大於start
  4. 縮放範圍: scale建議在0.1-5.0範圍內
  5. 位置參數: transform_x和transform_y單位為像素，但內部會轉換為半畫布單位存儲
    • transform_x轉換公式：實際值 / 960（假設畫布寬度1920）
    • transform_y轉換公式：實際值 / 540（假設畫布高度1080）
  6. 軌道管理: 系統自動創建貼紙軌道
  7. 性能考慮: 避免同時添加大量貼紙

工作流程

  1. 驗證必填參數（draft_url, sticker_id, start, end）
  2. 檢查時間範圍的有效性
  3. 從緩存中獲取草稿
  4. 創建貼紙軌道（如果不存在）
  5. 創建圖像調節設置
  6. 創建貼紙片段
  7. 添加片段到軌道
  8. 保存草稿
  9. 返回貼紙信息

相關接口

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

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