ADD_CAPTIONS API 接口文档

接口信息

POST /openapi/capcut-tools/v1/add_captions

功能描述

向现有草稿中批量添加字幕。该接口用于在指定的时间段内添加字幕到剪映草稿中，支持丰富的字幕样式设置，包括文本颜色、边框颜色、对齐方式、透明度、字体、字体大小、字间距、行间距、缩放和位置调整等。

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

请求参数

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

参数说明

参数名	类型	必填	默认值	说明
draft_url	string	✅	-	目标草稿的完整 URL
captions	string	✅	-	字幕信息列表的 JSON 字符串
text_color	string	❌	"#ffffff"	文本颜色（十六进制）
border_color	string	❌	null	边框颜色（十六进制）
alignment	integer	❌	1	文本对齐方式（0-5）
alpha	number	❌	1.0	文本透明度（0.0-1.0）
font	string	❌	null	字体名称
font_size	integer	❌	15	字体大小
letter_spacing	number	❌	null	字间距
line_spacing	number	❌	null	行间距
scale_x	number	❌	1.0	水平缩放比例
scale_y	number	❌	1.0	垂直缩放比例
transform_x	integer	❌	0	X 轴位置偏移（像素）
transform_y	integer	❌	0	Y 轴位置偏移（像素）
style_text	boolean	❌	false	是否使用样式文本

captions 字段详细说明

captions 是一个 JSON 字符串，包含字幕数组，每个字幕对象包含以下字段：

| 字段名 | 类型 | 必填 | 默认值 | 说明 | | ----------------------- | ------- | ---- | --------- | -------------------- | ---------------- | | start | integer | ✅ | - | 字幕开始时间（微秒） | | end | integer | ✅ | - | 字幕结束时间（微秒） | | text | string | ✅ | - | 字幕文本内容 | | keyword | string | ❌ | null | 关键词（用 | 分隔多个关键词） | | keyword_color | string | ❌ | "#ff7100" | 关键词颜色 | | keyword_font_size | integer | ❌ | 15 | 关键词字体大小 | | font_size | integer | ❌ | 15 | 文本字体大小 | | in_animation | string | ❌ | null | 入场动画 | | out_animation | string | ❌ | null | 出场动画 | | loop_animation | string | ❌ | null | 循环动画 | | in_animation_duration | integer | ❌ | null | 入场动画时长 | | out_animation_duration | integer | ❌ | null | 出场动画时长 | | loop_animation_duration | integer | ❌ | null | 循环动画时长 |

参数详解

时间参数

start: 字幕在时间轴上的开始时间，单位为微秒（1 秒 = 1,000,000 微秒）
end: 字幕在时间轴上的结束时间，单位为微秒
duration: 字幕显示时长 = end - start

对齐方式说明

值	说明
0	左对齐
1	居中对齐
2	右对齐
3	垂直居中
4	垂直左对齐
5	垂直右对齐

缩放参数

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

响应字段说明

字段名	类型	说明
draft_url	string	更新后的草稿 URL
track_id	string	字幕轨道 ID
text_ids	array	字幕 ID 列表
segment_ids	array	字幕片段 ID 列表
segment_infos	array	片段信息列表

错误响应 (4xx/5xx)

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

使用示例

cURL 示例

1. 基本字幕添加

curl -X POST https://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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
  }'

错误码说明

错误码	错误信息	说明	解决方案
400	draft_url 是必填项	缺少草稿 URL 参数	提供有效的 draft_url
400	captions 是必填项	缺少字幕信息参数	提供有效的 captions
400	无效的字幕信息，请检查 captions 字段格式是否正确	字幕参数验证失败	检查字幕参数是否符合要求
400	时间范围无效	end 必须大于 start	确保结束时间大于开始时间
404	草稿不存在	指定的草稿 URL 无效	检查草稿 URL 是否正确
500	字幕添加失败	内部处理错误	联系技术支持

注意事项

时间单位: 所有时间参数使用微秒（1 秒 = 1,000,000 微秒）
字幕时长: end 时间必须大于 start 时间
颜色格式: 颜色值使用十六进制格式，如 "#ffffff"、"#ff0000"
字体限制: 部分字体可能不支持，默认使用系统字体
对齐限制: 部分对齐方式可能不支持，默认使用系统对齐
动画效果: 动画名称需系统支持才能使用默认动画
对齐方式: 当前仅支持水平对齐方式（0-2），垂直对齐方式（3-5）为系统保留
位置转换: transform_x 和 transform_y 使用像素值，最终会转换为草稿相对位置
缩放建议: scale_x 和 scale_y 建议在合理范围内使用

工作流程

验证必填参数（draft_url, captions）
检查时间范围有效性
异步下载草稿
创建字幕轨道（如果不存在）
解析字幕信息，创建字幕片段
添加片段到轨道
保存草稿
返回字幕信息