如何使用 Pokerai API 校验并规范化扑克牌串？
在需要牌张的工作流中使用前，将一个紧凑牌串发送到公开 PokerKit 规范化端点。
直接答案：调用
POST /v1/pokerkit/cards/normalize 并提供必填 cards 字符串。公开 CardsRequest 示例为 AsKsQs；依赖任何响应字段前，请查看当前 Reference。Quick facts
| 事项 | 公开契约 |
|---|---|
| 操作 | POST /v1/pokerkit/cards/normalize |
| 必填请求体 | cards，字符串。 |
| 公开示例 | AsKsQs。 |
| 牌张记法 | 每张牌由两字符组成：点数 AKQJT98765432 后接花色 c、d、h 或 s；多张牌不加分隔符直接拼接。 |
| 成功响应 | 公开文档定义 HTTP 200，但 OpenAPI 的响应 schema 是开放的。应检查实际返回 JSON，不要把字段名视为固定 contract。 |
最小 OpenAPI 请求
curl -s https://pokerai.bet/v1/pokerkit/cards/normalize \
-H "Authorization: Bearer $POKERAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cards":"AsKsQs"}'该请求使用公开 CardsRequest 示例。一次真实成功调用会返回 HTTP 200 和 JSON；当前公开 snapshot 有意不限定该响应 schema，因此请检查实际 JSON，不要硬编码未公开字段名。
可接受输入与规范化边界
使用 As、Kd、Th 等紧凑两字符牌，并拼接成 AsKsQs 一类字符串。此端点只校验和规范化牌张输入；不计算 equity、不评估手牌、不推荐行动，也不推断策略。
常见错误与隐私
| 信号 | 公开契约 | 处理方式 |
|---|---|---|
HTTP 422 | HTTPValidationError | 检查 cards 是否存在且为 JSON 字符串，再按当前 Reference 核对提交的记法。 |
| 鉴权 | 该操作列出 Authorization 与 X-API-Key 请求头。 | 二选一发送支持的 API-key header；参见鉴权。 |
| 隐私 | 牌张可能属于敏感牌局或用户数据。 | 只提交必要内容；不要将 API key 写进请求体或日志；牌串可能关联玩家或手牌历史时，在支持材料中应脱敏。 |
规范化只用于训练、教学、复盘、学习和研究流程。它不是真钱实时辅助（RTA），不提供策略，也不得用于指导真实牌桌行动。
相关文档
- Docs hub — PokerKit 与 GTO API 总览。
- 扑克手牌分析指南 — 在牌局结束后的分析流程中使用规范化牌张输入。
- API Reference — 当前端点级请求和响应详情。
- OpenAPI snapshot — 公开的
CardsRequest与响应 contract。 - Python SDK、TypeScript / JavaScript SDK 和 MCP server — 官方 package 入口。
禁止在真实资金牌桌上提供实时辅助。