快速开始
如何 5 分钟接入棋牌AI API
三步走：获取 API Key → 创建AI对局 → 推送事件获取决策。以下示例均可直接复制运行，完整对接现有牌局逻辑一般 1-3 天。
最后更新：2026年10月 · 适用于 API v1.1
1
注册并获取 API Key
在注册页创建团队账号后，控制台会生成两把密钥：Publishable Key（客户端展示用量）与 Secret Key（服务端调用）。Secret Key 通过环境变量注入，切勿写入前端代码或提交到仓库。
bash — 配置密钥
export ZHENREN_API_KEY="sk_live_xxxxxxxxxxxxxxxx"
# 建议：写入 .env 并加入 .gitignore2
创建AI对局
调用创建对局接口，路径中的 {game}为玩法 id（ddz2 / ddz3 / ddz4 / shmj / scmj / gdmj / guandan / shengji / slots）。robots 指定机器人数量，difficulty 推荐使用 human-like 档位。
bash — 创建三人斗地主AI对局
curl -X POST https://api.zhenren.com.cn/v1/games/ddz3/sessions \
-H "Authorization: Bearer $ZHENREN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"robots": 2,
"difficulty": "human-like",
"emotion": "enabled",
"personas": ["steady", "aggressive"]
}'json — 响应
{
"session_id": "sess_9f2ek4m1",
"game": "ddz3",
"status": "running",
"robots": [
{ "id": "bot_a7c3", "seat": 1, "persona": "steady" },
{ "id": "bot_b1d9", "seat": 2, "persona": "aggressive" }
],
"decision_p95_ms": 48
}3
推送事件，获取AI决策
建立 WebSocket 连接后，按牌局发生顺序上报事件（发牌、真人出牌、聊天等）， AI 会在其回合返回决策消息：出牌内容、决策延迟、情绪状态与可选聊天文案。 回合制玩法也可用 HTTP 轮询替代。
Node.js — 推送与接收
import { ZhenrenAI } from "@zhenren/sdk";
const ai = new ZhenrenAI(process.env.ZHENREN_API_KEY!);
const session = await ai.sessions.create("ddz3", {
robots: 2,
difficulty: "human-like",
emotion: true,
});
session.on("decision", (d) => {
// { action: "play", cards: ["S2"],
// latency_ms: 41, chat_suggest: "..." }
applyRobotMove(d);
});
session.push({ type: "deal", hands: [...] });Python — 推送与接收
from zhenren import ZhenrenAI
ai = ZhenrenAI(api_key=os.environ["ZHENREN_API_KEY"])
session = ai.sessions.create(
"scmj",
robots=3,
difficulty="human-like",
emotion=True,
)
for decision in session.stream():
# decision.action / decision.cards
# decision.emotion / decision.chat_suggest
apply_robot_move(decision)
session.push({"type": "deal", "hands": [...]})FAQ
快速开始常见问题
接入棋牌AI API需要什么技术条件？+
只需要一个能发起 HTTP/WebSocket 请求的服务端。你的房间系统、客户端、结算逻辑完全不用改，AI 只承担机器人座位的决策。
支持哪些语言的示例代码？+
官方提供 Node.js（TypeScript）、Python、Java、Go 四种 SDK，快速开始文档内示例均可直接复制运行。