如何用 API 处理扑克范围？

使用 PokerKit range endpoint 将已文档化 notation 转为具体 combo、分析确定性的范围属性，或使用明确的 Monte-Carlo 控制估计范围 equity；当任务是 solver range workflow 时，使用已公开的 GTO range endpoint。

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

直接答案：使用 POST /v1/pokerkit/range/expand 扩展 notation。使用 /range/value 和 /range/nut-advantage 做确定性的基于 board 的范围分析；需要 Monte-Carlo equity-share estimate 时使用 /range/equity-advantage。对 solver-derived range，使用公开的 /v1/gto/range、/v1/gto/flop/projected-range 或 /v1/gto/turn/projected-range contract。

Quick facts

Notation	PokerKit range notation 数组，例如 `["AA", "KQs"]`；expand 返回具体两张牌 combo。
确定性	`range/expand`、`range/value` 与 `range/nut-advantage` 不使用 Monte-Carlo sampling。
Monte-Carlo	`range/equity-advantage` 接受已文档化的 `sample_count` 和 `seed`；seed 支持可复现 sampling。
配额	确定性的 PokerKit range endpoint 各消耗 1 次 general quota。`range/equity-advantage` 消耗 1 次 solve quota。
GTO ranges	GTO range endpoint 是独立的 solver workflow。请从 Reference 或 OpenAPI snapshot 读取当前 request/response schema。
用途边界	仅用于训练、教学、手牌复盘、学习和研究；不得用于真钱实时辅助。

Range notation

传入 notation string 的 JSON 数组。AA 表示口袋对子 hand class，KQs 表示 suited king-queen；expand 响应列出具体 card pair。请将 notation、board 和玩家顺序与复盘输入一同保存，以便结果可解释。

最小已验证请求与响应

此公开 docs-code 示例调用 POST /v1/pokerkit/range/expand。发送 API key 时使用 Authorization: Bearer $POKERAI_API_KEY 与 JSON content type。

{"notation": ["AA", "KQs"]}

{"result": [["Ac", "Ad"], ["Ac", "Ah"], ["Ac", "As"], ["Ad", "Ah"], ["Ad", "As"], ["Ah", "As"], ["Kc", "Qc"], ["Kd", "Qd"], ["Kh", "Qh"], ["Ks", "Qs"]]}

每个内层数组都是一个具体两张牌 combo。该响应解释的是提交的 notation，不是 GTO action recommendation。

选择 range operation

需求	公开 endpoint	方法
扩展 notation	`POST /v1/pokerkit/range/expand`	确定性的 combo expansion。
在 board 上构建 value range	`POST /v1/pokerkit/range/value`	用 `aggression` 或 `floor` 设置确定性的 made-category floor。
比较 nut share	`POST /v1/pokerkit/range/nut-advantage`	确定性的按 combo count 计算的 nut-share split。
比较 equity share	`POST /v1/pokerkit/range/equity-advantage`	两个已提交范围的 Monte-Carlo estimate；仅按文档使用 `sample_count` 和 `seed`。
推进 solver range	`POST /v1/gto/range`、`/flop/projected-range` 或 `/turn/projected-range`	适用于所述 solver workflow 的公开 GTO range contract。

确定性与 Monte-Carlo

不要把 expand、value 或 nut-advantage 的结果标为 simulation：这些 operation 对提交的输入是确定性的。equity-advantage 不同：它是 Monte-Carlo，因此结果是提交 ranges 与 board 的 estimate。固定 seed 使 sampling 可复现，不代表普遍精确；展示结果时保留返回的 sample_count。

配额和错误

信号	含义	处理方式
401	`missing_api_key` 或 `invalid_api_key`。	发送有效 API-key header；不要在客户端日志中暴露密钥。
429	适用的月度计数器耗尽时为 `quota_exceeded`。	等待重置或减少工作量；不要重试未改变的请求。
422	请求验证失败。	从当前 Reference 或 OpenAPI schema 检查 endpoint 并修正 body。

请在配额文档和 dashboard 查看当前计数器。GTO range endpoint 遵循各自已文档化的配额行为。

仅限训练和复盘

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