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

贴纸处理接口

简介

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

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

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

项目结构

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

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

#mermaid-svg-j9COBI8pAJ0XnDeJ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-j9COBI8pAJ0XnDeJ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-j9COBI8pAJ0XnDeJ .error-icon{fill:#552222;}#mermaid-svg-j9COBI8pAJ0XnDeJ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-j9COBI8pAJ0XnDeJ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-j9COBI8pAJ0XnDeJ .marker.cross{stroke:#333333;}#mermaid-svg-j9COBI8pAJ0XnDeJ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-j9COBI8pAJ0XnDeJ p{margin:0;}#mermaid-svg-j9COBI8pAJ0XnDeJ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-j9COBI8pAJ0XnDeJ .cluster-label text{fill:#333;}#mermaid-svg-j9COBI8pAJ0XnDeJ .cluster-label span{color:#333;}#mermaid-svg-j9COBI8pAJ0XnDeJ .cluster-label span p{background-color:transparent;}#mermaid-svg-j9COBI8pAJ0XnDeJ .label text,#mermaid-svg-j9COBI8pAJ0XnDeJ span{fill:#333;color:#333;}#mermaid-svg-j9COBI8pAJ0XnDeJ .node rect,#mermaid-svg-j9COBI8pAJ0XnDeJ .node circle,#mermaid-svg-j9COBI8pAJ0XnDeJ .node ellipse,#mermaid-svg-j9COBI8pAJ0XnDeJ .node polygon,#mermaid-svg-j9COBI8pAJ0XnDeJ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-j9COBI8pAJ0XnDeJ .rough-node .label text,#mermaid-svg-j9COBI8pAJ0XnDeJ .node .label text,#mermaid-svg-j9COBI8pAJ0XnDeJ .image-shape .label,#mermaid-svg-j9COBI8pAJ0XnDeJ .icon-shape .label{text-anchor:middle;}#mermaid-svg-j9COBI8pAJ0XnDeJ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-j9COBI8pAJ0XnDeJ .rough-node .label,#mermaid-svg-j9COBI8pAJ0XnDeJ .node .label,#mermaid-svg-j9COBI8pAJ0XnDeJ .image-shape .label,#mermaid-svg-j9COBI8pAJ0XnDeJ .icon-shape .label{text-align:center;}#mermaid-svg-j9COBI8pAJ0XnDeJ .node.clickable{cursor:pointer;}#mermaid-svg-j9COBI8pAJ0XnDeJ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-j9COBI8pAJ0XnDeJ .arrowheadPath{fill:#333333;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-j9COBI8pAJ0XnDeJ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-j9COBI8pAJ0XnDeJ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-j9COBI8pAJ0XnDeJ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-j9COBI8pAJ0XnDeJ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-j9COBI8pAJ0XnDeJ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-j9COBI8pAJ0XnDeJ .cluster text{fill:#333;}#mermaid-svg-j9COBI8pAJ0XnDeJ .cluster span{color:#333;}#mermaid-svg-j9COBI8pAJ0XnDeJ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-j9COBI8pAJ0XnDeJ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-j9COBI8pAJ0XnDeJ rect.text{fill:none;stroke-width:0;}#mermaid-svg-j9COBI8pAJ0XnDeJ .icon-shape,#mermaid-svg-j9COBI8pAJ0XnDeJ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-j9COBI8pAJ0XnDeJ .icon-shape p,#mermaid-svg-j9COBI8pAJ0XnDeJ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-j9COBI8pAJ0XnDeJ .icon-shape .label rect,#mermaid-svg-j9COBI8pAJ0XnDeJ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-j9COBI8pAJ0XnDeJ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-j9COBI8pAJ0XnDeJ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-j9COBI8pAJ0XnDeJ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 客户端
FastAPI 路由

/v1/add_sticker

/v1/search_sticker
请求模型

AddStickerRequest
请求模型

SearchStickerRequest
服务层

add_sticker()
服务层

search_sticker()
剪映草稿脚本

ScriptFile
贴纸轨道

TrackType.sticker
贴纸配置文件

sticker.json

核心组件

贴纸添加接口（/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 条以内

架构概览

贴纸处理接口的调用链如下：
"贴纸轨道" "剪映草稿脚本" "服务层" "路由层(v1)" "客户端" "贴纸轨道" "剪映草稿脚本" "服务层" "路由层(v1)" "客户端" #mermaid-svg-kO5cmZ7n0SKZq6no{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-kO5cmZ7n0SKZq6no .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-kO5cmZ7n0SKZq6no .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-kO5cmZ7n0SKZq6no .error-icon{fill:#552222;}#mermaid-svg-kO5cmZ7n0SKZq6no .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-kO5cmZ7n0SKZq6no .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-kO5cmZ7n0SKZq6no .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-kO5cmZ7n0SKZq6no .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-kO5cmZ7n0SKZq6no .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-kO5cmZ7n0SKZq6no .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-kO5cmZ7n0SKZq6no .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-kO5cmZ7n0SKZq6no .marker{fill:#333333;stroke:#333333;}#mermaid-svg-kO5cmZ7n0SKZq6no .marker.cross{stroke:#333333;}#mermaid-svg-kO5cmZ7n0SKZq6no svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-kO5cmZ7n0SKZq6no p{margin:0;}#mermaid-svg-kO5cmZ7n0SKZq6no .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-kO5cmZ7n0SKZq6no text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-kO5cmZ7n0SKZq6no .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-kO5cmZ7n0SKZq6no .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-kO5cmZ7n0SKZq6no .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-kO5cmZ7n0SKZq6no .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-kO5cmZ7n0SKZq6no #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-kO5cmZ7n0SKZq6no .sequenceNumber{fill:white;}#mermaid-svg-kO5cmZ7n0SKZq6no #sequencenumber{fill:#333;}#mermaid-svg-kO5cmZ7n0SKZq6no #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-kO5cmZ7n0SKZq6no .messageText{fill:#333;stroke:none;}#mermaid-svg-kO5cmZ7n0SKZq6no .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-kO5cmZ7n0SKZq6no .labelText,#mermaid-svg-kO5cmZ7n0SKZq6no .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-kO5cmZ7n0SKZq6no .loopText,#mermaid-svg-kO5cmZ7n0SKZq6no .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-kO5cmZ7n0SKZq6no .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-kO5cmZ7n0SKZq6no .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-kO5cmZ7n0SKZq6no .noteText,#mermaid-svg-kO5cmZ7n0SKZq6no .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-kO5cmZ7n0SKZq6no .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-kO5cmZ7n0SKZq6no .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-kO5cmZ7n0SKZq6no .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-kO5cmZ7n0SKZq6no .actorPopupMenu{position:absolute;}#mermaid-svg-kO5cmZ7n0SKZq6no .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-kO5cmZ7n0SKZq6no .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-kO5cmZ7n0SKZq6no .actor-man circle,#mermaid-svg-kO5cmZ7n0SKZq6no line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-kO5cmZ7n0SKZq6no :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} POST /v1/add_sticker 调用 add_sticker(...) 校验时间范围(end>start) 从缓存获取草稿创建贴纸轨道(若不存在) 构造ClipSettings(scale, transform_x/960, transform_y/540) 创建StickerSegment并添加到轨道保存草稿返回draft_url, sticker_id, track_id, segment_id, duration 200 OK POST /v1/search_sticker 调用 search_sticker(keyword) 读取config/sticker.json 关键词匹配/随机采样(<=50) 返回data列表 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
使用示例
- 基础贴纸添加、带缩放的贴纸、带位置偏移的贴纸

#mermaid-svg-z1bxFgIvSoBK4Rvf{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-z1bxFgIvSoBK4Rvf .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-z1bxFgIvSoBK4Rvf .error-icon{fill:#552222;}#mermaid-svg-z1bxFgIvSoBK4Rvf .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-z1bxFgIvSoBK4Rvf .marker{fill:#333333;stroke:#333333;}#mermaid-svg-z1bxFgIvSoBK4Rvf .marker.cross{stroke:#333333;}#mermaid-svg-z1bxFgIvSoBK4Rvf svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-z1bxFgIvSoBK4Rvf p{margin:0;}#mermaid-svg-z1bxFgIvSoBK4Rvf .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-z1bxFgIvSoBK4Rvf .cluster-label text{fill:#333;}#mermaid-svg-z1bxFgIvSoBK4Rvf .cluster-label span{color:#333;}#mermaid-svg-z1bxFgIvSoBK4Rvf .cluster-label span p{background-color:transparent;}#mermaid-svg-z1bxFgIvSoBK4Rvf .label text,#mermaid-svg-z1bxFgIvSoBK4Rvf span{fill:#333;color:#333;}#mermaid-svg-z1bxFgIvSoBK4Rvf .node rect,#mermaid-svg-z1bxFgIvSoBK4Rvf .node circle,#mermaid-svg-z1bxFgIvSoBK4Rvf .node ellipse,#mermaid-svg-z1bxFgIvSoBK4Rvf .node polygon,#mermaid-svg-z1bxFgIvSoBK4Rvf .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-z1bxFgIvSoBK4Rvf .rough-node .label text,#mermaid-svg-z1bxFgIvSoBK4Rvf .node .label text,#mermaid-svg-z1bxFgIvSoBK4Rvf .image-shape .label,#mermaid-svg-z1bxFgIvSoBK4Rvf .icon-shape .label{text-anchor:middle;}#mermaid-svg-z1bxFgIvSoBK4Rvf .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-z1bxFgIvSoBK4Rvf .rough-node .label,#mermaid-svg-z1bxFgIvSoBK4Rvf .node .label,#mermaid-svg-z1bxFgIvSoBK4Rvf .image-shape .label,#mermaid-svg-z1bxFgIvSoBK4Rvf .icon-shape .label{text-align:center;}#mermaid-svg-z1bxFgIvSoBK4Rvf .node.clickable{cursor:pointer;}#mermaid-svg-z1bxFgIvSoBK4Rvf .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-z1bxFgIvSoBK4Rvf .arrowheadPath{fill:#333333;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-z1bxFgIvSoBK4Rvf .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-z1bxFgIvSoBK4Rvf .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-z1bxFgIvSoBK4Rvf .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-z1bxFgIvSoBK4Rvf .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-z1bxFgIvSoBK4Rvf .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-z1bxFgIvSoBK4Rvf .cluster text{fill:#333;}#mermaid-svg-z1bxFgIvSoBK4Rvf .cluster span{color:#333;}#mermaid-svg-z1bxFgIvSoBK4Rvf div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-z1bxFgIvSoBK4Rvf .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-z1bxFgIvSoBK4Rvf rect.text{fill:none;stroke-width:0;}#mermaid-svg-z1bxFgIvSoBK4Rvf .icon-shape,#mermaid-svg-z1bxFgIvSoBK4Rvf .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-z1bxFgIvSoBK4Rvf .icon-shape p,#mermaid-svg-z1bxFgIvSoBK4Rvf .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-z1bxFgIvSoBK4Rvf .icon-shape .label rect,#mermaid-svg-z1bxFgIvSoBK4Rvf .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-z1bxFgIvSoBK4Rvf .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-z1bxFgIvSoBK4Rvf .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-z1bxFgIvSoBK4Rvf :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 否
是
进入 add_sticker
校验参数与时间范围
end > start ?
返回 400 参数错误
从缓存获取草稿
创建贴纸轨道(若不存在)
构建图像调节设置

scale, transform_x/960, transform_y/540
创建贴纸片段
添加到轨道
保存草稿
返回 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 条
使用示例
- 关键词"人"搜索、关键词"动物"搜索

#mermaid-svg-8RLRmr7IjBXCDN86{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-8RLRmr7IjBXCDN86 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-8RLRmr7IjBXCDN86 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-8RLRmr7IjBXCDN86 .error-icon{fill:#552222;}#mermaid-svg-8RLRmr7IjBXCDN86 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-8RLRmr7IjBXCDN86 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-8RLRmr7IjBXCDN86 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-8RLRmr7IjBXCDN86 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-8RLRmr7IjBXCDN86 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-8RLRmr7IjBXCDN86 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-8RLRmr7IjBXCDN86 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-8RLRmr7IjBXCDN86 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-8RLRmr7IjBXCDN86 .marker.cross{stroke:#333333;}#mermaid-svg-8RLRmr7IjBXCDN86 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-8RLRmr7IjBXCDN86 p{margin:0;}#mermaid-svg-8RLRmr7IjBXCDN86 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-8RLRmr7IjBXCDN86 .cluster-label text{fill:#333;}#mermaid-svg-8RLRmr7IjBXCDN86 .cluster-label span{color:#333;}#mermaid-svg-8RLRmr7IjBXCDN86 .cluster-label span p{background-color:transparent;}#mermaid-svg-8RLRmr7IjBXCDN86 .label text,#mermaid-svg-8RLRmr7IjBXCDN86 span{fill:#333;color:#333;}#mermaid-svg-8RLRmr7IjBXCDN86 .node rect,#mermaid-svg-8RLRmr7IjBXCDN86 .node circle,#mermaid-svg-8RLRmr7IjBXCDN86 .node ellipse,#mermaid-svg-8RLRmr7IjBXCDN86 .node polygon,#mermaid-svg-8RLRmr7IjBXCDN86 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-8RLRmr7IjBXCDN86 .rough-node .label text,#mermaid-svg-8RLRmr7IjBXCDN86 .node .label text,#mermaid-svg-8RLRmr7IjBXCDN86 .image-shape .label,#mermaid-svg-8RLRmr7IjBXCDN86 .icon-shape .label{text-anchor:middle;}#mermaid-svg-8RLRmr7IjBXCDN86 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-8RLRmr7IjBXCDN86 .rough-node .label,#mermaid-svg-8RLRmr7IjBXCDN86 .node .label,#mermaid-svg-8RLRmr7IjBXCDN86 .image-shape .label,#mermaid-svg-8RLRmr7IjBXCDN86 .icon-shape .label{text-align:center;}#mermaid-svg-8RLRmr7IjBXCDN86 .node.clickable{cursor:pointer;}#mermaid-svg-8RLRmr7IjBXCDN86 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-8RLRmr7IjBXCDN86 .arrowheadPath{fill:#333333;}#mermaid-svg-8RLRmr7IjBXCDN86 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-8RLRmr7IjBXCDN86 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-8RLRmr7IjBXCDN86 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8RLRmr7IjBXCDN86 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-8RLRmr7IjBXCDN86 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8RLRmr7IjBXCDN86 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-8RLRmr7IjBXCDN86 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-8RLRmr7IjBXCDN86 .cluster text{fill:#333;}#mermaid-svg-8RLRmr7IjBXCDN86 .cluster span{color:#333;}#mermaid-svg-8RLRmr7IjBXCDN86 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-8RLRmr7IjBXCDN86 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-8RLRmr7IjBXCDN86 rect.text{fill:none;stroke-width:0;}#mermaid-svg-8RLRmr7IjBXCDN86 .icon-shape,#mermaid-svg-8RLRmr7IjBXCDN86 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8RLRmr7IjBXCDN86 .icon-shape p,#mermaid-svg-8RLRmr7IjBXCDN86 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-8RLRmr7IjBXCDN86 .icon-shape .label rect,#mermaid-svg-8RLRmr7IjBXCDN86 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8RLRmr7IjBXCDN86 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-8RLRmr7IjBXCDN86 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-8RLRmr7IjBXCDN86 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
否
进入 search_sticker
读取 config/sticker.json
按 keyword 在 title 中匹配
是否有匹配?
限制返回数量<=50
随机采样<=50条
返回 data 列表

贴纸 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
- 贴纸添加依赖剪映草稿脚本与轨道系统

#mermaid-svg-OS7QsPJxfUyQ4iaw{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-OS7QsPJxfUyQ4iaw .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-OS7QsPJxfUyQ4iaw .error-icon{fill:#552222;}#mermaid-svg-OS7QsPJxfUyQ4iaw .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-OS7QsPJxfUyQ4iaw .marker{fill:#333333;stroke:#333333;}#mermaid-svg-OS7QsPJxfUyQ4iaw .marker.cross{stroke:#333333;}#mermaid-svg-OS7QsPJxfUyQ4iaw svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-OS7QsPJxfUyQ4iaw p{margin:0;}#mermaid-svg-OS7QsPJxfUyQ4iaw .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-OS7QsPJxfUyQ4iaw .cluster-label text{fill:#333;}#mermaid-svg-OS7QsPJxfUyQ4iaw .cluster-label span{color:#333;}#mermaid-svg-OS7QsPJxfUyQ4iaw .cluster-label span p{background-color:transparent;}#mermaid-svg-OS7QsPJxfUyQ4iaw .label text,#mermaid-svg-OS7QsPJxfUyQ4iaw span{fill:#333;color:#333;}#mermaid-svg-OS7QsPJxfUyQ4iaw .node rect,#mermaid-svg-OS7QsPJxfUyQ4iaw .node circle,#mermaid-svg-OS7QsPJxfUyQ4iaw .node ellipse,#mermaid-svg-OS7QsPJxfUyQ4iaw .node polygon,#mermaid-svg-OS7QsPJxfUyQ4iaw .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-OS7QsPJxfUyQ4iaw .rough-node .label text,#mermaid-svg-OS7QsPJxfUyQ4iaw .node .label text,#mermaid-svg-OS7QsPJxfUyQ4iaw .image-shape .label,#mermaid-svg-OS7QsPJxfUyQ4iaw .icon-shape .label{text-anchor:middle;}#mermaid-svg-OS7QsPJxfUyQ4iaw .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-OS7QsPJxfUyQ4iaw .rough-node .label,#mermaid-svg-OS7QsPJxfUyQ4iaw .node .label,#mermaid-svg-OS7QsPJxfUyQ4iaw .image-shape .label,#mermaid-svg-OS7QsPJxfUyQ4iaw .icon-shape .label{text-align:center;}#mermaid-svg-OS7QsPJxfUyQ4iaw .node.clickable{cursor:pointer;}#mermaid-svg-OS7QsPJxfUyQ4iaw .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-OS7QsPJxfUyQ4iaw .arrowheadPath{fill:#333333;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-OS7QsPJxfUyQ4iaw .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-OS7QsPJxfUyQ4iaw .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-OS7QsPJxfUyQ4iaw .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-OS7QsPJxfUyQ4iaw .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-OS7QsPJxfUyQ4iaw .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-OS7QsPJxfUyQ4iaw .cluster text{fill:#333;}#mermaid-svg-OS7QsPJxfUyQ4iaw .cluster span{color:#333;}#mermaid-svg-OS7QsPJxfUyQ4iaw div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-OS7QsPJxfUyQ4iaw .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-OS7QsPJxfUyQ4iaw rect.text{fill:none;stroke-width:0;}#mermaid-svg-OS7QsPJxfUyQ4iaw .icon-shape,#mermaid-svg-OS7QsPJxfUyQ4iaw .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-OS7QsPJxfUyQ4iaw .icon-shape p,#mermaid-svg-OS7QsPJxfUyQ4iaw .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-OS7QsPJxfUyQ4iaw .icon-shape .label rect,#mermaid-svg-OS7QsPJxfUyQ4iaw .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-OS7QsPJxfUyQ4iaw .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-OS7QsPJxfUyQ4iaw .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-OS7QsPJxfUyQ4iaw :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 路由 v1
service.add_sticker
service.search_sticker
schemas.add_sticker
schemas.search_sticker
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. 测试参考

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

文档信息

接口文档： docs.jcaigc.cn
效果案例： www.jcaigc.cn/workflow
开源仓库： capcut-mate