ADD_STICKER API 接口文档
接口信息
POST /openapi/capcut-tools/v1/add_sticker
功能描述
向现有草稿中添加贴纸。该接口用于在指定的时间段内添加贴纸素材到剪映草稿中，支持贴纸的缩放和位置调整。贴纸可以用于增强视频的视觉效果，如表情、装饰、文字等。
更多文档
📖 更多详细文档和教程请访问：https://docs.agent-ai-tools.com
请求参数
{
"draft_url": "https://agent.aigc-ai.com/openapi/capcut-tools/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 | ❌ | 0 | X 轴位置偏移（像素） |
| transform_y | number | ❌ | 0 | 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://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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://agent.aigc-ai.com/openapi/capcut-tools/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,000,000 微秒）
- 贴纸 ID: 确保使用有效的贴纸 ID
- 时间范围: end 必须大于 start
- 缩放范围: scale 建议在 0.1-5.0 范围内
- 位置参数: transform_x 和 transform_y 单位为像素，但内部会转换为半画布单位存储
- transform_x 转换公式：实际值 / 960（假设画布宽度 1920）
- transform_y 转换公式：实际值 / 540（假设画布高度 1080）
- 轨道管理: 系统自动创建贴纸轨道
- 性能考虑: 避免同时添加大量贴纸
工作流程
- 验证必填参数（draft_url, sticker_id, start, end）
- 检查时间范围的有效性
- 从缓存中获取草稿
- 创建贴纸轨道（如果不存在）
- 创建贴纸资源设置
- 创建贴纸片段
- 添加片段到轨道
- 保存草稿
- 返回贴纸信息