托管贴纸运行时

将 MediaRuntime 用作应用的贴纸后端。

激活托管贴纸包,在应用合集内启用它,然后使用与该合集绑定的输入联想、搜索、元数据查询和短效资源 URL 解析功能。工作区 API 密钥必须始终保存在可信服务器上。

概览
贴纸包
一组已发布、付费且带版本的贴纸资源,可供工作区使用。
合集
一项免费的应用配置,用于控制某个应用能够发现哪些已激活的贴纸包。
贴纸
通过搜索选取并使用获准变体渲染的稳定元数据记录。
设置

合集不会购买贴纸包

合集是一项免费的应用配置,作用于工作区已经激活的托管贴纸包。停用某个贴纸包会使其不再出现在新的搜索和输入联想结果中;保留原有绑定则可继续准确渲染历史消息。

  1. 01

    激活托管贴纸包

    付费激活权益归工作区所有。

  2. 02

    创建合集

    每个应用或贴纸策略边界应使用一个独立合集。

  3. 03

    启用贴纸包

    此后,合集便可通过运行时读取接口提供该贴纸包。

交互契约

输入联想是搜索的起点,而不是贴纸查询

输入联想返回 海滩 之类的建议词。搜索用户选中的建议词后,才会返回贴纸记录。调用元数据和 resolve 接口时,请持久化并传入 stickerIdsemanticId 仅用于描述语义,不能用作贴纸路径标识符。

Bash

使用 CLI 测试完整流程

# The API key stays in trusted server-side environment configuration.
export MEDIARUNTIME_API_KEY="sk_..."
collection_id='stc_11111111111111111111111111111111'

# Typeahead returns suggestion text, not stickers or delivery URLs.
mediaruntime stickers typeahead "海"   --collection "$collection_id"   --locale zh-CN   --limit 10   --json

# Search the selected suggestion to obtain complete sticker records.
mediaruntime stickers search "海滩"   --collection "$collection_id"   --limit 10   --json

# Use stickerId—not semanticId—for metadata and asset routes.
sticker_id='sage-the-owl-summer-season-vacation-v1-beach-day'
mediaruntime stickers get "$sticker_id" --collection "$collection_id" --json

# Resolve only when the UI needs an approved representation.
mediaruntime stickers resolve "$sticker_id"   --variant small_160   --collection "$collection_id"   --json
官方 SDK

在应用代码中实现相同的合集绑定流程。

使用 Node SDK 实现输入联想
// npm install @mediaruntime/node
import { MediaRuntime } from "@mediaruntime/node";

// Never expose the workspace API key in browser or mobile code.
const media = new MediaRuntime({ apiKey: process.env.MEDIARUNTIME_API_KEY });
const stickers = media.stickers.collection("stc_11111111111111111111111111111111");

// Show these suggestion texts while the user types.
const typeahead = await stickers.typeahead("海", { locale: "zh-CN", limit: 10 });
const selectedTerm = typeahead.suggestions[0]?.text;
if (!selectedTerm) throw new Error("No sticker suggestion matched");

// Search turns the selected term into stable sticker records.
const matches = await stickers.search(selectedTerm, { limit: 10 });
const selectedSticker = matches.items[0];
if (!selectedSticker) throw new Error("No sticker matched the selected suggestion");

// Persist stickerId in the message; signed delivery URLs expire.
const asset = await stickers.resolve(selectedSticker.stickerId, "small_160");
console.log(selectedSticker.stickerId, asset.url);

服务器密钥或限定范围的客户端令牌

可信服务器可以直接使用 MEDIARUNTIME_API_KEY。浏览器和移动应用应使用由可信服务器按需签发的短效令牌,并将其权限限定为一个合集和明确的运行时权限范围(scope)。

持久化引用,而非 URL

请随消息保存 stickerIdpackIdpackVersion。由于固定到特定生成版本的交付 URL 会按设计在短时间后失效,因此应在渲染时解析获准变体。

REST 参考

贴纸合集与运行时端点

方法路径用途
GET/v1/sticker-collections列出工作区拥有的应用合集。
PUT/v1/sticker-collections/{collection_id}/packs/{pack_id}在一个合集中启用已经激活的托管贴纸包。
GET/v1/stickers/packs列出明确指定的 collection_id 中已启用的贴纸包。
GET/v1/stickers/typeahead返回与语言区域相匹配的建议词;不会返回贴纸 ID。
GET/v1/stickers/search搜索已启用的贴纸元数据,并返回稳定的 stickerId 值。
GET/v1/stickers/{sticker_id}使用 stickerId(而不是 semanticId)获取一张贴纸。
GET/v1/stickers/{sticker_id}/assets/{variant}返回固定到特定生成版本的短效交付 URL。
POST/v1/sticker-runtime/client-tokens按需签发限定合集范围的短效客户端令牌。
GET/v1/sticker-runtime/usage/current查看当前共享池中的操作用量和已授权交付用量。