AI 助理
文档备案控制台
开发者社区 阿里云百炼 文章 正文

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

2026-05-29 204
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： 本文档详解贴纸处理接口：/v1/add_sticker（支持时间轴定位、缩放/位置调节与层级渲染）和/v1/search_sticker（关键词检索贴纸配置），涵盖架构设计、核心流程、参数规范、性能优化及故障排查，助力高效集成剪映贴纸能力。（239字）

贴纸处理接口

目录

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

  • 贴纸搜索测试
    • 正常搜索、无匹配随机返回、空关键词场景
  • 简化版贴纸搜索测试
    • 与服务层逻辑一致的简化实现
文章标签：
大模型服务平台百炼
缓存
运维
存储
开发者
1575030468644753
目录
相关文章
看山Agent架构
|
1月前
|
人工智能 分布式计算 安全
多Agent协同系统：从"协作工具"到"战略生产系统"的架构演进
本文以"枢衡"多Agent集群的架构升级为例，探讨了多Agent协同系统在生产环境中面临的典型问题，以及如何通过角色专业化、Skill收敛、信誉积分、双模式工作法和通信纪律等机制，将松散的Agent问答组演进为具备质量闭环的战略生产系统
看山Agent架构
247 0
多Agent协同系统：从"协作工具"到"战略生产系统"的架构演进
1575030468644753
|
1月前
|
监控 中间件 API
【剪映小助手】音频时间线计算接口（Audio Timelines）
音频时间线计算接口用于草稿自动化中音视频时序分析，依赖requests、subprocess、Pydantic等模块，支持并发处理、流式下载与断点续传。含参数校验、错误重试及自动清理机制，OpenAPI为准。
1575030468644753
172 12
1575030468644753
|
1月前
|
JSON 自然语言处理 前端开发
【开源剪映小助手】项目概述
capcut-mate 是一款开源免费、支持独立部署的剪映自动化系统，基于 FastAPI 构建，深度融合大模型能力，提供草稿创建、素材编排、云端渲染、本地导出及智能编辑等全链路功能，助力内容创作者高效批量生产专业视频。（239字）
1575030468644753
349 1
小林学AI
|
1月前
|
存储 人工智能 安全
别再被AI Agent配置折腾了！Hermes Agent 保姆级攻略，10分钟避坑上手
本文从快速配置、核心模块详解、常用示例、问题排查四方面，带你完成Hermes Agent全流程配置。新手用 hermes setup 快速上手，进阶用户可手动编辑 config.yaml 定制记忆、网关、安全等模块。
小林学AI
1030 2
golang学习记
|
1月前
|
人工智能 前端开发 Shell
OpenAI 给 Codex 加了个 @ 功能，我的工作效率直接起飞
Codex TUI 新增智能 `@` 提及功能：一键唤起文件、插件、Skills三合一补全，支持颜色标签、路径自动引号、图片附件等细节优化，大幅降低上下文切换成本，让终端编程更流畅自然。（239字）
golang学习记
548 0
1575030468644753
|
1月前
|
缓存 监控 数据库连接
【剪映小助手】添加贴纸接口（Add Sticker）
添加贴纸接口（`/v1/add_sticker`）用于在剪映草稿指定时间段内自动化添加贴纸，支持缩放、位移与时间轴精准控制，依赖草稿引擎与贴纸配置，具备缓存优化与错误诊断能力。（239字）
1575030468644753
135 2
1575030468644753
|
1月前
|
存储 缓存 JSON
【剪映小助手】添加音频接口（Add Audios）
本文档介绍草稿自动化中音频接口的集成方案，涵盖用途说明、组件依赖（含外部库与内部模块）、性能优化（下载、内存、并发）、常见错误码及排查指南，并强调以OpenAPI为准的字段与校验规范。（239字）
1575030468644753
151 4
卿云阁
|
1月前
|
机器学习/深度学习 数据可视化 机器人
PyTorch深度学习实战 |手算​​自编码Autoencoder
自编码器是一种无监督神经网络，通过编码器将数据压缩为低维潜在表示，再由解码器重建原始输入。其核心价值在于自动提取关键特征、实现降维与数据去噪，广泛应用于图像重建、特征学习和可视化分析等领域。
卿云阁
175 3
卿云阁
|
1月前
|
机器学习/深度学习 存储 编解码
PyTorch深度学习实战 | 手算卷积网络（Resnet-18)
ResNet-18是解决深层网络梯度消失与退化问题的经典模型，核心在于残差连接（Shortcut）：让输入X直接跳跃传递，与卷积学习的残差F(X)相加（F(X)+X），实现恒等映射。其含4个stage、18层可训练层，每个BasicBlock由两个3×3卷积+BN+ReLU构成，并通过1×1卷积适配尺寸/通道差异，显著提升深层网络训练稳定性与性能。（239字）
卿云阁
221 2
XinIRP
|
1月前
|
人工智能 算法 中间件
意图共鸣科技《认知智能白皮书》——记忆主权到认知主权：认知操作系统（COS）的底层逻辑
本文提出“认知操作系统”（COS）——一种运行于大模型之上的智能中间件，专司AI对人情世故、分寸边界与潜规则的理解与响应。它守护用户“认知主权”，强调透明、可审计、可参与的进化机制，并以数学化方式锁死生命安全等文明底线。
XinIRP
240 1

阿里云百炼

热门文章

最新文章

  • 1
    数据中心网络带宽线速有门道
  • 2
    从零搭建企业私有知识库：RAG + 大模型实战（附完整代码）
  • 3
    阿里云百炼 API 调用教程：准备 API-Key、配置环境变量和调用 API 流程
  • 4
    阿里云百炼平台详解：官网入口链接、免费AI大模型领取及常见问题解答FAQ
  • 5
    阿里云百炼Token Plan三大档位详解：Credits计费规则、Token换算与团队选型指南
  • 6
    阿里云百炼API Key获取全流程：免费额度领取与新手调用配置指南
  • 7
    最新版阿里云百炼 Night Plan 功能介绍
  • 8
    阿里云百炼平台全解：入口、免费额度与常见问题一站式指南
  • 9
    阿里云AI产品专属活动：从模型到应用最新优惠权益解析
  • 10
    阿里云百炼上线DeepSeek-V4：API 价格与官网一致，百万Tokens输入最低1元、输出最低2元
  • 1
    【剪映小助手】异常处理系统（Exception Handling System）
    19
  • 2
    阿里云百炼 Token Plan 全解析：个人版与团队版支持模型、套餐定价、API调用实战教程
    29
  • 3
    最新版 Qwen Code（终端 AI 编程工具） 功能介绍及接入阿里云百炼 Coding Plan、Token Plan 教程
    32
  • 4
    最新版 Cursor（AI 编程 IDE） 功能介绍及接入阿里云百炼 Coding Plan、Token Plan 教程
    48
  • 5
    Token Plan个人版功能介绍：三档套餐定价、Credits抵扣规则与Qwen3.8限时折扣实操教程
    28
  • 6
    阿里云百炼API Key从零上手全教程：免费额度申领+密钥配置+首次调用实战
    25
  • 7
    新版百炼Token Plan个人版全解：三档套餐权益、抵扣规则、模型适配实操指南
    24
  • 8
    【剪映小助手】特效信息生成接口（Effect Infos）
    36
  • 9
    年中汇报做了三天PPT？我用百炼CLI一条命令批量生成了50份
    38
  • 10
    新版 阿里云百炼 Token Plan 功能介绍，助力 AI 生产力，全模型通用节省计划直省 55%
    44

    • 相关电子书

    更多
  • 低代码开发师（初级）实战教程
  • 冬季实战营第三期：MySQL数据库进阶实战
  • 阿里巴巴DevOps 最佳实践手册
    • 下一篇
    一条命令迁移，帮你实现 OpenClaw 与 Hermes Agent 记忆互通！