概览
- 贴纸包
- 一组已发布、付费且带版本的贴纸资源,可供工作区使用。
- 合集
- 一项免费的应用配置,用于控制某个应用能够发现哪些已激活的贴纸包。
- 贴纸
- 通过搜索选取并使用获准变体渲染的稳定元数据记录。
设置
合集不会购买贴纸包
合集是一项免费的应用配置,作用于工作区已经激活的托管贴纸包。停用某个贴纸包会使其不再出现在新的搜索和输入联想结果中;保留原有绑定则可继续准确渲染历史消息。
- 01
激活托管贴纸包
付费激活权益归工作区所有。
- 02
创建合集
每个应用或贴纸策略边界应使用一个独立合集。
- 03
启用贴纸包
此后,合集便可通过运行时读取接口提供该贴纸包。
交互契约
输入联想是搜索的起点,而不是贴纸查询
输入联想返回 海滩 之类的建议词。搜索用户选中的建议词后,才会返回贴纸记录。调用元数据和 resolve 接口时,请持久化并传入 stickerId;semanticId 仅用于描述语义,不能用作贴纸路径标识符。
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
请随消息保存 stickerId、packId 和 packVersion。由于固定到特定生成版本的交付 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 | 查看当前共享池中的操作用量和已授权交付用量。 |