ADD_CAPTIONS API 接口文檔

接口信息

POST /openapi/capcut-mate/v1/add_captions

功能描述

向現有草稿中批量添加字幕。該接口用於在指定的時間段內添加字幕到剪映草稿中，支持豐富的字幕樣式設置，包括文本顏色、邊框顏色、對齊方式、透明度、字體、字體大小、字間距、行間距、縮放和位置調整等。

更多文檔

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

請求參數

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "captions": "[{\"start\":0,\"end\":10000000,\"text\":\"你好，剪映\",\"keyword\":\"好\",\"keyword_color\":\"#457616\",\"keyword_font_size\":15,\"font_size\":15}]",
  "text_color": "#ffffff",
  "border_color": null,
  "alignment": 1,
  "alpha": 1.0,
  "font": null,
  "font_size": 15,
  "letter_spacing": null,
  "line_spacing": null,
  "scale_x": 1.0,
  "scale_y": 1.0,
  "transform_x": 0,
  "transform_y": 0,
  "style_text": false
}

參數説明

captions字段詳細説明

captions是一個JSON字符串，包含字幕數組，每個字幕對象包含以下字段：

參數詳解

時間參數

• start: 字幕在時間軸上的開始時間，單位為微秒（1秒 = 1,000,000微秒）
• end: 字幕在時間軸上的結束時間，單位為微秒
• duration: 字幕顯示時長 = end - start

對齊方式説明

縮放參數

• scale_x: 字幕的水平縮放比例

  • 1.0 = 原始大小
  • 0.5 = 水平縮小到一半
  • 2.0 = 水平放大到兩倍

• scale_y: 字幕的垂直縮放比例

  • 1.0 = 原始大小
  • 0.5 = 垂直縮小到一半
  • 2.0 = 垂直放大到兩倍

位置參數

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

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

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

  • 正值向下移動
  • 負值向上移動
  • 以畫布中心為原點
  • 實際存儲時會轉換為半畫布高單位（假設畫布高度1080，即除以540）

響應格式

成功響應 (200)

{
  "draft_url": "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/get_draft?draft_id=2025092811473036584258",
  "track_id": "text_track_123",
  "text_ids": ["text_001", "text_002"],
  "segment_ids": ["seg_001", "seg_002"],
  "segment_infos": [
    {
      "id": "seg_001",
      "start": 0,
      "end": 5000000
    },
    {
      "id": "seg_002",
      "start": 5000000,
      "end": 10000000
    }
  ]
}

響應字段説明

錯誤響應 (4xx/5xx)

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

使用示例

cURL 示例

1. 基本字幕添加

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"你好，剪映\"}]",
    "text_color": "#ffffff",
    "alignment": 1,
    "alpha": 1.0,
    "font_size": 20
  }'

2. 多字幕添加

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"你好，剪映\"},{\"start\":5000000,\"end\":10000000,\"text\":\"歡迎使用字幕功能\"}]",
    "text_color": "#ffffff",
    "alignment": 1,
    "alpha": 1.0,
    "font_size": 16
  }'

3. 帶樣式和位置的字幕

curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/add_captions \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "YOUR_DRAFT_URL",
    "captions": "[{\"start\":0,\"end\":5000000,\"text\":\"你好，剪映\",\"keyword\":\"好\",\"keyword_color\":\"#ff0000\"}]",
    "text_color": "#ffffff",
    "alignment": 1,
    "alpha": 1.0,
    "font_size": 20,
    "scale_x": 1.2,
    "scale_y": 1.2,
    "transform_x": 100,
    "transform_y": -50
  }'

錯誤碼説明

注意事項

1. 時間單位: 所有時間參數使用微秒（1秒 = 1,000,000微秒）
2. 字幕時長: end 時間必須大於 start 時間
3. 顏色格式: 顏色值使用十六進制格式，如 "#ffffff"、"#ff0000"
4. 關鍵詞高亮: 暫未完全實現，目前為預留功能
5. 動畫效果: 暫未完全實現，目前為預留功能
6. 字體支持: 字體名稱需要系統支持或使用默認字體
7. 對齊方式: 目前僅支持基礎對齊方式（0-2），高級對齊方式（3-5）為預留功能
8. 座標系統: transform_x 和 transform_y 使用像素值，會自動轉換為草稿相對座標
9. 縮放參數: scale_x 和 scale_y 建議在合理範圍內使用

工作流程

1. 驗證必填參數（draft_url, captions）
2. 檢查時間範圍的有效性
3. 從緩存中獲取草稿
4. 創建字幕軌道（如果不存在）
5. 遍歷字幕信息，創建字幕片段
6. 添加片段到軌道
7. 保存草稿
8. 返回字幕信息

相關接口

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

<div align="right">

📚 項目資源
GitHub搜索capcut-mate就能找到。

</div>