贴纸处理接口

简介

本文档介绍贴纸处理接口，重点覆盖两个接口：

/v1/add_sticker：贴纸添加接口，支持在指定时间段内向剪映草稿中添加贴纸，可配置缩放与位置偏移
/v1/search_sticker：贴纸搜索接口，支持按关键词检索贴纸列表

文档说明请求参数、时间线定位机制、缩放与位置配置、层级关系与渲染顺序、透明度与动画效果的应用方式，并提供贴纸 ID 获取、贴纸预览与效果配置的示例与最佳实践。

项目结构

贴纸处理接口位于后端服务的 v1 路由模块中，采用“路由 → 模型（Schema）→ 服务（Service）”的分层设计：

路由层：定义 /v1/add_sticker 与 /v1/search_sticker 的 HTTP 接口与响应模型
模型层：使用 Pydantic 定义请求与响应的数据结构
服务层：实现具体的业务逻辑，包括贴纸添加与贴纸搜索
数据与配置：贴纸搜索依赖本地配置文件；贴纸添加依赖剪映草稿脚本与轨道系统

graph TB
Client["客户端"] --> Router["FastAPI 路由<br/>/v1/add_sticker<br/>/v1/search_sticker"]
Router --> SchemaAdd["请求模型<br/>AddStickerRequest"]
Router --> SchemaSearch["请求模型<br/>SearchStickerRequest"]
Router --> ServiceAdd["服务层<br/>add_sticker()"]
Router --> ServiceSearch["服务层<br/>search_sticker()"]
ServiceAdd --> Draft["剪映草稿脚本<br/>ScriptFile"]
ServiceAdd --> Track["贴纸轨道<br/>TrackType.sticker"]
ServiceSearch --> Config["贴纸配置文件<br/>sticker.json"]
Config --> ServiceSearch

核心组件

贴纸添加接口（/v1/add_sticker）
- 请求参数：draft_url、sticker_id、start、end、scale、transform_x、transform_y
- 处理流程：参数校验 → 时间范围验证 → 从缓存获取草稿 → 创建贴纸轨道 → 构造图像调节设置（含缩放与位置）→ 创建贴纸片段 → 添加到轨道 → 保存草稿 → 返回 track_id、segment_id、duration
贴纸搜索接口（/v1/search_sticker）
- 请求参数：keyword
- 处理流程：读取贴纸配置文件 → 关键词匹配 → 若无匹配则随机返回最多 50 条 → 截断至 50 条以内

架构概览

贴纸处理接口的调用链如下：

sequenceDiagram
participant C as "客户端"
participant R as "路由层(v1)"
participant S as "服务层"
participant D as "剪映草稿脚本"
participant T as "贴纸轨道"
C->>R : POST /v1/add_sticker
R->>S : 调用 add_sticker(...)
S->>S : 校验时间范围(end>start)
S->>D : 从缓存获取草稿
S->>T : 创建贴纸轨道(若不存在)
S->>S : 构造ClipSettings(scale, transform_x/960, transform_y/540)
S->>D : 创建StickerSegment并添加到轨道
S->>D : 保存草稿
S-->>R : 返回draft_url, sticker_id, track_id, segment_id, duration
R-->>C : 200 OK
C->>R : POST /v1/search_sticker
R->>S : 调用 search_sticker(keyword)
S->>S : 读取config/sticker.json
S->>S : 关键词匹配/随机采样(<=50)
S-->>R : 返回data列表
R-->>C : 200 OK

详细组件分析

贴纸添加接口 /v1/add_sticker

接口地址：/openapi/capcut-mate/v1/add_sticker
方法：POST
请求体字段
- draft_url：草稿 URL（必填）
- sticker_id：贴纸唯一标识（必填）
- start：开始时间（微秒，必填）
- end：结束时间（微秒，必填）
- scale：缩放比例，默认 1.0（建议范围 0.1–5.0）
- transform_x：X 轴位置偏移（像素，以画布中心为原点，默认 0）
- transform_y：Y 轴位置偏移（像素，以画布中心为原点，默认 0）
时间线定位机制
- 贴纸在时间轴上的起止由 start 与 end 决定，持续时间为 duration = end - start
- 时间范围必须满足 end > start，否则返回参数错误
缩放与位置配置
- scale 控制贴纸的缩放比例，1.0 表示原始尺寸
- transform_x 与 transform_y 以像素为单位传入，内部转换为“半画布宽/高”单位进行存储：
  - transform_x 存储值 = transform_x / 960（假设画布宽度 1920）
  - transform_y 存储值 = transform_y / 540（假设画布高度 1080）
层级关系与渲染顺序
- 贴纸轨道类型为 sticker，渲染顺序高于视频、音频、特效、滤镜、文本等轨道
- 轨道创建时使用唯一名称，确保同一草稿中贴纸轨道隔离
透明度与动画效果
- 透明度通过图像调节设置中的 alpha 字段控制（范围 0–1）
- 动画效果可通过关键帧与片段动画实现（见“性能考量”与“附录”）
响应字段
- draft_url：更新后的草稿 URL
- sticker_id：贴纸唯一标识
- track_id：贴纸轨道 ID
- segment_id：贴纸片段 ID
- duration：贴纸显示时长（微秒）
错误处理
- 参数缺失或 end ≤ start：返回 400
- 草稿不存在或无效：返回 404
- 内部处理异常：返回 500
使用示例
- 基础贴纸添加、带缩放的贴纸、带位置偏移的贴纸

flowchart TD
Start(["进入 add_sticker"]) --> Validate["校验参数与时间范围"]
Validate --> Valid{"end > start ?"}
Valid --> |否| Err["返回 400 参数错误"]
Valid --> |是| GetDraft["从缓存获取草稿"]
GetDraft --> CreateTrack["创建贴纸轨道(若不存在)"]
CreateTrack --> BuildSettings["构建图像调节设置<br/>scale, transform_x/960, transform_y/540"]
BuildSettings --> CreateSegment["创建贴纸片段"]
CreateSegment --> AddToTrack["添加到轨道"]
AddToTrack --> Save["保存草稿"]
Save --> Return["返回 track_id, segment_id, duration"]

贴纸搜索接口 /v1/search_sticker

接口地址：/openapi/capcut-mate/v1/search_sticker
方法：POST
请求体字段
- keyword：关键词（必填）
响应字段
- data：贴纸数据列表，每项包含：
  - sticker：贴纸详细信息（large_image、preview_cover、sticker_package、sticker_type、track_thumbnail）
  - sticker_id：贴纸 ID
  - title：贴纸标题
搜索策略
- 从配置文件加载贴纸数据
- 基于关键词在标题中进行包含匹配
- 若无匹配结果，随机返回最多 50 条记录
- 结果集超过 50 条时截断至 50 条
使用示例
- 关键词“人”搜索、关键词“动物”搜索

flowchart TD
S0(["进入 search_sticker"]) --> ReadCfg["读取 config/sticker.json"]
ReadCfg --> Match["按 keyword 在 title 中匹配"]
Match --> Found{"是否有匹配?"}
Found --> |是| Limit["限制返回数量<=50"]
Found --> |否| Sample["随机采样<=50条"]
Limit --> Done["返回 data 列表"]
Sample --> Done

贴纸 ID 获取、贴纸预览与贴纸效果配置

贴纸 ID 获取
- 通过 /v1/search_sticker 获取贴纸列表后，从响应 data 中提取 sticker_id
贴纸预览
- large_image.image_url 为贴纸大图 URL，track_thumbnail 为轨道缩略图 URL
贴纸效果配置
- 透明度：通过图像调节设置中的 alpha（0–1）控制
- 动画效果：可结合关键帧与片段动画实现（参见“性能考量”与“附录”）

依赖分析

路由到服务
- /v1/add_sticker → service.add_sticker
- /v1/search_sticker → service.search_sticker
服务到模型
- 请求模型：AddStickerRequest、SearchStickerRequest
- 响应模型：AddStickerResponse、SearchStickerResponse
服务到外部
- 贴纸搜索依赖 config/sticker.json
- 贴纸添加依赖剪映草稿脚本与轨道系统

graph LR
V1["路由 v1"] --> A["service.add_sticker"]
V1 --> B["service.search_sticker"]
A --> S["schemas.add_sticker"]
B --> S2["schemas.search_sticker"]
B --> C["config/sticker.json"]

性能考量

贴纸搜索
- 配置文件一次性加载，建议对大规模贴纸数据启用分页与缓存机制
- 随机采样上限为 50，避免一次性返回过多数据
贴纸添加
- 自动创建贴纸轨道，避免重复创建带来的开销
- 位置偏移转换为半画布单位，减少后续计算成本
动画与透明度
- 透明度与关键帧可叠加使用，建议合理设置关键帧密度，避免过度插值导致渲染压力

故障排查指南

/v1/add_sticker 常见问题
- 参数缺失或 end ≤ start：检查请求体字段完整性与时间范围
- 草稿不存在：确认 draft_url 有效且草稿已缓存
- 贴纸添加失败：检查贴纸 ID 是否存在、轨道是否创建成功
/v1/search_sticker 常见问题
- 关键词未命中：尝试更宽泛的关键词或检查配置文件是否存在
- 返回空列表：确认配置文件路径与权限

结论

贴纸处理接口提供了完整的贴纸添加与搜索能力。通过清晰的参数模型与稳健的服务实现，开发者可以便捷地在剪映草稿中添加贴纸、控制其时间、缩放与位置，并通过关键词快速检索贴纸资源。

建议在生产环境中结合缓存与分页策略优化贴纸搜索性能，并合理使用透明度与关键帧实现丰富的动画效果。

附录

A. 请求与响应模型

贴纸添加请求模型
- 字段：draft_url、sticker_id、start、end、scale、transform_x、transform_y
- 默认值：scale=1.0，transform_x=0，transform_y=0
贴纸添加响应模型
- 字段：draft_url、sticker_id、track_id、segment_id、duration
贴纸搜索请求模型
- 字段：keyword
贴纸搜索响应模型
- 字段：data（贴纸项列表）

B. 贴纸数据结构

贴纸项（StickerItem）
- 包含：sticker（StickerInfo）、sticker_id、title
贴纸信息（StickerInfo）
- 包含：large_image（LargeImage）、preview_cover、sticker_package（StickerPackage）、sticker_type、track_thumbnail
大图信息（LargeImage）
- 包含：image_url
贴纸包信息（StickerPackage）
- 包含：height_per_frame、size、width_per_frame

C. 贴纸轨道与渲染顺序

贴纸轨道类型：sticker
渲染顺序：高于视频、音频、特效、滤镜、文本等轨道
轨道创建：按需创建，名称唯一

D. 图像调节设置与透明度

图像调节设置（ClipSettings）
- 字段：alpha（透明度，0–1）、scale_x/scale_y（缩放）、transform_x/transform_y（半画布单位）
透明度控制：通过 alpha 设置，0 为完全透明，1 为不透明

E. 测试参考

贴纸搜索测试
- 正常搜索、无匹配随机返回、空关键词场景
简化版贴纸搜索测试
- 与服务层逻辑一致的简化实现

【剪映小助手】贴纸处理接口