API 参考
接口技术规格（v1.1）
基础地址、认证、端点、错误码与限流的完整定义。v1 系列向前兼容：只增不改，废弃提前 90 天公告。
最后更新：2026年10月 · 基础地址 https://api.zhenren.com.cn
认证
所有请求使用 Bearer Token 认证，Token 在控制台生成。Secret Key 仅限服务端使用；客户端展示用量请使用 Publishable Key + 用户级签名。
http — 请求头
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json端点总览
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /v1/games/{game}/sessions | 创建AI对局。game 为玩法 id，body 指定机器人数、难度、情绪与填充模式。 |
| GET | /v1/sessions/{session_id} | 查询会话状态：牌局进度、机器人列表、当前情绪上下文。 |
| POST | /v1/sessions/{session_id}/events | HTTP 通道推送牌局事件（deal/play/chat/timeout），返回AI当次决策。 |
| WS | /v1/sessions/{session_id}/stream | WebSocket 实时双向流：上行事件推送，下行决策与状态通知，支持自动重连。 |
| PATCH | /v1/sessions/{session_id}/config | 运行中调整会话参数：难度档位、情绪模式、胜率策略、填充比例。 |
| POST | /v1/sessions/{session_id}/end | 结束会话并触发结算回报（含本局调控审计日志引用）。 |
| GET | /v1/usage | 查询计费周期内决策调用量、按玩法分布与配额余量。 |
创建对局
POST /v1/games/{game}/sessions，game 取值：ddz2、ddz3、ddz4（斗地主）、shmj、scmj、gdmj（麻将）、guandan（掼蛋）、shengji（升级拖拉机）、slots。
请求体参数
{
"robots": 3, // 必填：机器人数量 1-3
"difficulty": "human-like", // rule|easy|human-like|strong
"emotion": "enabled", // 情绪感知开关
"personas": [ // 可选：性格档案
"steady", "aggressive", "casual"
],
"fill_mode": "dynamic", // full|dynamic（冷启动填充）
"robot_ratio_target": 0.35, // dynamic 模式目标AI占比
"win_rate": { // 可选：胜率策略
"target_range": [0.45, 0.55],
"hard_cap": 0.58 // 系统强制上限
},
"metadata": { "table_id": "t-2049" }
}响应 200
{
"session_id": "sess_9f2ek4m1",
"game": "scmj",
"status": "running",
"robots": [
{ "id": "bot_a7c3", "seat": 1,
"persona": "steady" },
{ "id": "bot_b1d9", "seat": 2,
"persona": "aggressive" },
{ "id": "bot_c4e2", "seat": 3,
"persona": "casual" }
],
"decision_p95_ms": 46,
"created_at": "2026-10-02T09:30:12Z"
}决策消息（下行）
机器人回合到达时，通过 WebSocket 下行或 HTTP 响应返回决策。牌张编码： 花色（S/H/D/C）+ 点数（2-9/T/J/Q/K/A），王牌为 JR/JB；麻将使用 tile id（如 W2T=二筒）。
json — 决策消息
{
"type": "decision",
"session_id": "sess_9f2ek4m1",
"robot_id": "bot_a7c3",
"seq": 87,
"action": "play", // play|pass|bid|chi|pon|kan|riichi…
"cards": ["H7", "H8", "H9"],
"latency_ms": 41, // 本次决策耗时
"think_ms": 1650, // 拟人化思考时长（建议驱动前端表现）
"emotion": "neutral", // neutral|encouraging|calm|focused
"chat_suggest": "顺子走一个", // 可选：互动文案建议
"audit_ref": "adt_7f11" // 调控审计日志引用
}错误码
| HTTP | error | 说明与处理 |
|---|---|---|
| 401 | unauthorized | API Key 缺失或无效，检查 Authorization 头 |
| 402 | quota_exceeded | 超出套餐配额，升级套餐或等待周期重置 |
| 404 | session_not_found | 会话不存在或已过期（会话保留 72 小时） |
| 422 | invalid_event | 事件格式或牌型非法，检查 cards 编码 |
| 429 | rate_limited | 触发限流，按 Retry-After 头退避重试 |
| 500 | internal_error | 服务端异常，自动重试建议采用指数退避 |
限流
单 Key 默认 600 req/min、50 并发会话/万次套餐配额，超限返回 429 并附带 Retry-After。更高并发随套餐提升。
超时
决策接口建议客户端超时 2s；AI 决策 P95 < 50ms，超时多为网络链路问题，可安全重试。
幂等
events 接口支持 Idempotency-Key 头，重复推送同一事件不会产生重复决策。
延伸
更详细的规范
OpenAPI 3.1 规范文件与 Postman 集合随 SDK 仓库一同发布，路径见 SDK 与示例页。