Douyin Mini Game Server Api

Comprehensive skill reference for Douyin (TikTok China) mini-game server-side OpenAPI. Covers HTTPS API interfaces for backend developers — access token management, login credential verification, user data storage, QR code generation, subscription messages, gift redemption, Link/Schema generation, dynamic sharing, game group tags, and all server-side `mgplatform/api` endpoints. Use when developing, debugging, or asking questions about Douyin mini-game backend APIs — especially the server-side login flow (code2Session/checkSessionKey/resetSessionKey), access token (getAccessToken/genStableAccessToken), user cloud storage (setUserStorage/removeUserStorage), QR codes (createQRCode), subscription notifications, gift reward verification, or any OpenAPI SDK integration.

WuFengSheng@wufengsheng

Install

openclaw skills install @wufengsheng/douyin-mini-game-server-api

基于抖音小游戏服务端 OpenAPI 官方文档生成，生成时间 2026-06-24 官方文档: https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/server/

抖音小游戏服务端 OpenAPI 是提供给开发者服务端调用的 HTTPS API 接口集合。用于在开发者后台服务器上完成登录凭证校验、用户数据管理、二维码生成、消息推送、礼包核销等功能。所有 API 域名基于 https://minigame.zijieapi.com/mgplatform/api/，Scope 均为 open.ttgame.mgplatform。支持 Java/NodeJS/Go 三种官方 SDK。

概述与 SDK

模块	描述	参考文件
服务端 API 概述	access_token 机制、请求格式规范、OpenAPI SDK 总览（Java/NodeJS/Go）、完整 API 接口列表（21个接口）	server-overview

核心 API

接口调用凭证

模块	描述	参考文件
接口调用凭证	getAccessToken（获取全局调用凭据，2h 有效期）、genStableAccessToken（稳定版 token，普通/强制刷新两种模式）	server-auth

模块	描述	参考文件
登录相关	code2Session（登录凭证校验，获取 openid/session_key/unionid）、用户登录态签名（hmac_sha256 签名规则）、checkSessionKey（校验登录态）、resetSessionKey（重置登录态）	server-login

数据与二维码

模块	描述	参考文件
数据缓存	setUserStorage（写入用户云存储数据，支持排行榜 KVData 格式）、removeUserStorage（删除用户数据）、存储限制（key≤128B, key+value≤1024B, ≤128对）	server-data
二维码	createQRCode（生成二维码/抖音码，支持圆形码、自定义颜色、icon、版本控制、启动参数）	server-qrcode

消息与其它

模块	描述	参考文件
消息推送	订阅消息发送（模板消息推送，1次/秒限制）、消息推送客服（回复文字客服消息）	server-message
其他能力	游戏礼包核销、Link链接（生成/查询/配额）、Schema链接（生成/查询/配额）、动态分享（活动ID/更新动态消息）、游戏群标签（查询/设置）、公会群解绑、赛事上报、内容安全检测、广告变现数据 API	server-other

快速参考

access_token 机制

text

获取: POST /api/apps/v2/token (getAccessToken) 或 POST /api/apps/stable_token (genStableAccessToken)
有效期: 2小时（getAccessToken 重复获取会使旧 token 缩短至 5 分钟）
稳定版: genStableAccessToken 在有效期内返回不变 token，两种模式（普通/强制刷新）

核心认证流程

javascript

// 1. 获取 access_token
const tokenRes = await fetch('https://minigame.zijieapi.com/mgplatform/api/apps/v2/token', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ appid: 'ttxxx', secret: 'xxx', grant_type: 'client_credential' })
});
const { data: { access_token } } = await tokenRes.json();

// 2. code2Session 校验登录
const loginRes = await fetch(
  `https://minigame.zijieapi.com/mgplatform/api/apps/jscode2session?appid=ttxxx&secret=xxx&code=${code}`
);
const { openid, session_key, unionid } = await loginRes.json();

// 3. 生成用户登录态签名（hmac_sha256）
const crypto = require('crypto');
function sign(sessionKey, method, uriPath, postBody) {
  let data = method.toLowerCase() + '&' + encodeURIComponent(uriPath);
  if (postBody) data += '&' + postBody;
  return crypto.createHmac('sha256', sessionKey).update(data).digest('hex');
}

// 4. 写用户数据（带签名）
const signature = sign(session_key, 'post', '/mgplatform/api/apps/set_user_storage', body);
await fetch('https://minigame.zijieapi.com/mgplatform/api/apps/set_user_storage?...', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ kv_list: [{ key: 'score', value: '100' }] })
});

SDK 快速选择

语言	SDK 包	适用场景
Java	`com.douyin.openapi:sdk:1.0.5`	企业级后端服务
NodeJS	`@open-dy/open_api_sdk`	Node.js 后端服务
Go	`github.com/bytedance/douyin-openapi-sdk-go`	Go 微服务

API 速查表

功能	API URL（相对路径）	Method	需要签名
获取 token	/api/apps/v2/token	POST	否
稳定 token	/api/apps/stable_token	POST	否
登录校验	/api/apps/jscode2session	GET	否
校验 session	/api/apps/check_session_key	GET	是
重置 session	/api/apps/reset_session_key	POST	是
写用户数据	/api/apps/set_user_storage	POST	是
删用户数据	/api/apps/remove_user_storage	POST	是
生成二维码	/api/apps/qrcode	POST	否
发送订阅消息	/api/apps/subscribe_notification/developer/v1/notify	POST	否
核销礼包	/api/gift/receive_reward	POST	否
回复客服消息	/api/apps/reply/reply_user_text	POST	否

最佳实践

Token 管理：推荐使用 genStableAccessToken，避免多服务实例互刷 token；单实例可用 getAccessToken 每小时刷新
AppSecret 安全：永远只在服务端使用 AppSecret，不下发到客户端或外部
签名正确性：涉及用户数据的 API 必须正确生成 hmac_sha256 签名，注意 POST body 的 JSON 字符串要与签名时一致
频率控制：注意各 API 的限频（如二维码 5000次/分钟、订阅消息 1次/秒/用户），实现指数退避重试
错误处理：针对 access_token 过期（28001008）和无效（28001003）自动刷新重试
幂等设计：礼包核销使用 uuid 保证幂等，防止重复发放
SDK 优先：优先使用官方 OpenAPI SDK，减少自行实现签名和 token 刷新逻辑
session_key 保护：session_key 仅在服务端保存，不通过任何方式下发到客户端