贴纸处理接口详解

目录

简介

今天我们来深入拆解贴纸处理接口的两个核心端点，它们是您在剪映草稿中灵活操控贴纸元素的关键工具。

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

本文将详细说明请求参数、时间线定位机制、缩放与位置配置、层级关系与渲染顺序、透明度与动画效果的应用方式，同时提供贴纸 ID 获取、贴纸预览与效果配置的示例和最佳实践，帮助您快速上手。

项目结构

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

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

graph TB
Client["客户端"] --> Router["FastAPI 路由
/v1/add_sticker
/v1/search_sticker"]
Router --> SchemaAdd["请求模型
AddStickerRequest"]
Router --> SchemaSearch["请求模型
SearchStickerRequest"]
Router --> ServiceAdd["服务层
add_sticker()"]
Router --> ServiceSearch["服务层
search_sticker()"]
ServiceAdd --> Draft["剪映草稿脚本
ScriptFile"]
ServiceAdd --> Track["贴纸轨道
TrackType.sticker"]
ServiceSearch --> Config["贴纸配置文件
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["构建图像调节设置
scale, transform_x/960, transform_y/540"]
BuildSettings --> CreateSegment["创建贴纸片段"]
CreateSegment --> AddToTrack["添加到轨道"]
AddToTrack --> Sa ve["保存草稿"]
Sa ve --> 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. 测试参考

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