VectCutAPI

主题

search_sticker ​

POST /search_sticker

接口说明 ​

按关键词搜索服务端本地保存的剪映贴纸索引，返回贴纸 ID、大小、宽高比例、URL 和格式。这个接口不调用第三方搜索 API，也不保存贴纸图片；用户选中后把 sticker_id 传给 add_sticker。

按关键词搜索剪映贴纸，返回剪映 sticker_id、大小、宽高比例、素材 URL、格式和数量。结果不返回预览图字段。搜索结果随后交给 add_sticker 写入草稿。

这个接口搜索的是什么 ​

它搜索的是剪映贴纸索引，不是服务自己制作的贴纸图片库。

  • 索引中的 sticker_id 来自剪映贴纸资源。
  • 草稿只记录剪映 sticker_id，不下载或转存贴纸图片。
  • 打开草稿时，剪映会按该 ID 从剪映素材库加载贴纸。
  • 搜索只读取服务器本地 JSON 索引，不调用第三方搜索 API，也不需要 Token。

剪映网页版存在内部搜索接口，但匿名调用会返回 check sign error，必须携带客户端动态签名，不能作为稳定的自建接口使用。因此本服务采用本地索引方式。

请求参数 ​

参数类型必填默认值说明
keywordsstring是—搜索关键词，例如 生日快乐、箭头、爱心
countinteger否20返回数量，范围 1-50
offsetinteger否0分页偏移，从 0 开始；offset=2 表示跳过前两条

兼容参数名：也可以把 keywords 写成 keyword。

count 是本次返回条数，不是匹配总数。比如搜索“牛逼”共有 47 条匹配，传 count=3 时只返回 3 条，output.total 仍然显示 47。展示结果时只展示 sticker_id、size、aspect_ratio、url、format 和数量，不展示预览图。

请求示例 ​

bash
curl -X POST https://your-domain.example/api/search_sticker \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VECTCUT_API_KEY" \
  -d '{
    "keywords": "帽子",
    "count": 3,
    "offset": 0
  }'

返回示例 ​

json
{
  "success": true,
  "output": {
    "data": [
      {
        "sticker_id": "7050494369782123814",
        "size": 113433,
        "width": 540,
        "height": 540,
        "aspect_ratio": "1:1",
        "url": "https://cdn.example.com/sticker.png",
        "format": "png"
      }
    ],
    "total": 91,
    "offset": 0,
    "count": 3
  },
  "error": ""
}

这里只展示第一条；count=3 时实际会返回 3 条。url 是带签名的临时素材地址，写草稿时应使用稳定的 sticker_id。

返回字段 ​

字段类型说明
output.dataarray当前页的贴纸列表
output.data[].sticker_idstring剪映贴纸资源 ID，传给 add_sticker
output.data[].sizeinteger贴纸大小，单位字节
output.data[].widthinteger素材宽度
output.data[].heightinteger素材高度
output.data[].aspect_ratiostring宽高比例，例如 1:1、44:35
output.data[].urlstring贴纸素材 URL
output.data[].formatstring素材格式，例如 png、jpeg、gif
output.totalinteger匹配总数
output.offsetinteger当前分页偏移
output.countinteger当前页返回数量

本地索引配置 ​

默认路径：

text
data/sticker_catalog.json

也可以通过配置文件或环境变量修改：

json
{
  "sticker_catalog_path": "/opt/vectcutapi/data/sticker_catalog.json"
}
bash
export VECTCUT_STICKER_CATALOG_PATH=/opt/vectcutapi/data/sticker_catalog.json

索引文件可以是数组，也可以放在 data、items 或 stickers 字段中。服务接受以下常见字段名：

  • sticker_id、resource_id、resourceId、id
  • title、name
  • image_url、cover_url、preview_url、thumbnail_url
  • sticker_type、sticker_package

最小示例：

json
[
  {
    "sticker_id": "7069661365685832990",
    "title": "生日快乐，气球，庆祝",
    "keywords": ["生日", "气球", "庆祝"],
    "image_url": "https://example.com/sticker.gif",
    "thumbnail_url": "https://example.com/sticker-preview.png",
    "sticker_type": 2
  }
]

兼容的剪映贴纸搜索结果可以直接作为导入源，包括 output.data 里的 sticker.large_image.image_url、sticker.track_thumbnail、sticker.sticker_package 和 sticker_type。导入后服务只读取本地索引，不再请求原来的搜索服务。

素材 URL 通常带 x-expires 和 x-signature 参数，是剪映 CDN 的临时签名地址。签名过期后只影响 URL，不影响草稿中的 sticker_id；需要更新 URL 时应重新导入索引。

导入已有剪映贴纸索引 ​

如果你已经有从自己的剪映环境导出的贴纸 JSON，可以运行：

bash
python scripts/import_sticker_catalog.py \
  --input /path/to/your-stickers.json \
  --output data/sticker_catalog.json

需要保留已有条目时加 --merge。

常见错误 ​

错误原因处理
keywords is required没有传关键词传 keywords 或 keyword
sticker catalog not found本地索引不存在创建索引并配置 sticker_catalog_path
invalid sticker catalog JSON索引 JSON 格式错误检查逗号、引号和数组结构
count must be between 1 and 50返回数量超出范围把 count 调整到 1-50

个人自建服务

VectCutAPI