如何用 API 分析一手扑克牌？

将底牌和翻牌、转牌或河牌发送到 POST /v1/pokerkit/hand-report，获取已文档化的事实性手牌报告。

更新于 2026 年 7 月 27 日维护方 Pokerai API

直接答案：如需汇总 Hero 报告，请将 hole 与 board 提交到 POST /v1/pokerkit/hand-report。仅需牌面时，使用带 board 的 POST /v1/pokerkit/board-report 或 POST /v1/pokerkit/category-combos；使用带 hole 和 board 的 POST /v1/pokerkit/hand-tier、POST /v1/pokerkit/draws、POST /v1/pokerkit/outs 或 POST /v1/pokerkit/blockers；使用带 hole_range 的 POST /v1/pokerkit/hand-strength；使用 POST /v1/pokerkit/nuts 查看牌面的最强可成手牌与平分底池组合；并以带 cards 的 POST /v1/pokerkit/cards/normalize 校验和规范化牌码字符串。解读 result 前，请检查每个操作当前的 OpenAPI schema；仅将已结束手牌用于训练或复盘，不得用于真实资金牌桌行动选择。

核心事实

端点	`POST /v1/pokerkit/hand-report`
必填输入	公开 `HandRequest` schema 定义的 `hole`（两张底牌）与 `board`（3、4 或 5 张公共牌）
可选输入	公开 OpenAPI schema 定义的 `hand_type` 与 `dead`
已文档化报告	针对所提交手牌与牌面的 texture、成手 tier、draws、outs 和 blockers 上下文
用途边界	仅限训练、教学、已结束手牌复盘、学习和研究；禁止真实资金 RTA

输入语义

hole 是玩家的两张底牌，board 是由 3、4 或 5 张公共牌组成的牌面。将标准两字符牌码直接拼接，不使用分隔符。公开 HandRequest schema 还允许 hand_type 和 dead；除非已文档化的工作流需要，否则不要传入。

最小请求与响应

以下 curl 请求和响应是共享公开 pokerkitHandReport 示例。

curl -s https://pokerai.bet/v1/pokerkit/hand-report \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hole":"JhTh","board":"AsKsQs"}'

{"result":{"texture":{"cards":["As","Ks","Qs"],"wetness":{"name":"WET","value":"Wet"},"connectivity":{"name":"HIGH","value":"High"},"rank_band":{"name":"HIGH","value":"High"},"straight_draw":{"name":"OPEN_ENDED","value":"Open-ended"},"flush_draw":{"name":"LIVE","value":"Live"},"are_two_tone":false,"are_monotone":true,"are_rainbow":false},"tier":{"category":{"name":"STRAIGHT","value":"Straight"},"is_nut":false,"nut_rank":{"name":"NON_NUT","value":"Non-nut"}},"draws":{"straight_draw":null,"flush_draw":null,"nut_rank":null},"outs":{"by_category":{},"count":0}}}

如何解读报告

texture 描述所提交牌面：牌张、分类 wetness、connectivity、rank band、可用的 straight/flush draw 和花色形态布尔值。tier 对成手分类；本例中 category 为 Straight，且 is_nut 为 false。draws 记录剩余 straight/flush draw 标签及其 nut rank；本例为 null，表示没有报告这两类 draw。outs 按类别归组可改善牌张并给出 count；本例组为空，outs 为零。

公开文档将 Hand Report 描述为包含 texture、tier、draws、outs 和 blockers 的 Hero 概览；但上方共享公开响应示例没有 blockers 成员，客户端不得将其设为必需字段。若要检查已文档化的 blocker 字段，请使用独立的 POST /v1/pokerkit/blockers contract：它返回 nut combo 总数与已阻断数量、blocker cards、block fraction，以及 Hero 是否阻断 nuts。

适用场景

当 trainer、教学工具、手牌历史复盘、学习笔记或研究流程需要为一手已结束牌局标注事实性牌面和手牌标签时，使用 Hand Report。在展示其他独立文档化分析前，它可为 UI 提供一致的基础标签。

不适用场景

不要把描述性字段当作 equity、solver result、保证或推荐行动。不得将该端点接入 live-table feed、由输出自动行动，或用于真实资金实时辅助。

配额和错误

Hand Report 与公开 PokerKit API 使用相同的 API key 和账号配额体系。请在配额文档、定价页和 dashboard 中查看当前账号限制与用量，不要在客户端硬编码额度。公开 OpenAPI contract 声明了 422 验证响应；请依据当前 Reference 或 OpenAPI schema 修正 hole、board 和可选字段。鉴权与配额错误请使用当前错误文档处理，且不要重试未改变的无效请求。

SDK、MCP 与相关资源

开发者文档提供官方 SDK、MCP 设置、鉴权与配额说明。请在 API Reference 中查看当前操作，并查阅机器可读的 OpenAPI snapshot。官方入口包括 Python SDK、TypeScript / JavaScript SDK 和 MCP server。

禁止真实资金 RTA

Pokerai API 仅用于训练、教学、手牌复盘、学习和研究。禁止在真实资金牌桌上提供实时辅助。不要将手牌分析输出接入 live-table automation，也不要展示为实时行动指令。

端点	任务	用途
`POST /v1/pokerkit/hand-report`	分析一手牌和牌面	返回已文档化的组合手牌报告。
`POST /v1/pokerkit/blockers`	检查 blocker 证据	独立读取已文档化的 nut-combo blocker 字段。