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

贴纸处理接口

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构概览
5. 详细组件分析
6. 依赖分析
7. 性能考量
8. 故障排查指南
9. 结论
10. 附录

简介

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

• /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. 测试参考

• 贴纸搜索测试

  • 正常搜索、无匹配随机返回、空关键词场景

• 简化版贴纸搜索测试

  • 与服务层逻辑一致的简化实现