RakuXQDEVELOPER GUIDE
HTTP API · MULTIPART · JSON

用一张图片，
得到可计算的 FEN

上传 JPEG、PNG 或 WebP 棋盘图片。接口返回结构化 JSON；当 status 为 accepted 时，读取 fen 字段。

TRY IT NOW

领取 6 分钟临时 Key

尚未领取

同一网络在一个有效期内只能领取一个。Key 明文只显示一次、不可续期，适合调试，不适合生产。

首次领取前请明确接受服务与棋局训练授权及隐私说明。确认覆盖后续有权提交的棋局，不逐局弹窗；原图最多12小时，授权训练样本最多3年。训练采集尚未启用。版本记录
点击上方按钮后在这里显示，仅显示一次。

使用临时 Key 上传的原图同样会在官方服务器保留最多 12 小时，用于早期质量分析。

ENDPOINT

POST /v1/recognitions

Authorization
Bearer YOUR_API_KEY
image
必填，JPEG / PNG / WebP，最大 12 MB
side_to_move
red / black；缺失、空值或其他内容均按 auto
orientation
通常使用 auto

除明确的红方或黑方值以外，side_to_move 均按自动模式处理，表示你确认“原图下方是正在求助的我方”。程序直接比较帅、将在原始上传图片中的像素中心高度：帅在下返回红方走，将在下返回黑方走；棋盘旋转与标准化不会改变该结论，主帅证据不唯一时要求复核。

取得 fen 后可直接拼接到 https://xq.rakubank.com/fen/，打开原生棋局实验室；只需让浏览器把空格编码为 %20。

QUICK START

三种调用方式

领取临时 Key 后，下列示例会自动替换占位符。

curl
curl -X POST https://xq.rakubank.com/v1/recognitions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@board.jpg" \
  -F "side_to_move=auto" \
  -F "orientation=auto"
Python
import requests

response = requests.post(
    "https://xq.rakubank.com/v1/recognitions",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"image": open("board.jpg", "rb")},
    data={"side_to_move": "auto", "orientation": "auto"},
    timeout=60,
)
result = response.json()
fen = result["fen"] if result.get("status") == "accepted" else None
print(fen)
JavaScript
const form = new FormData();
form.append("image", file);
form.append("side_to_move", "auto");
form.append("orientation", "auto");

const response = await fetch("https://xq.rakubank.com/v1/recognitions", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
  body: form,
});
const result = await response.json();
console.log(result.status === "accepted" ? result.fen : null);
RESPONSE

成功响应

{
  "request_id": "...",
  "status": "accepted",
  "fen": "3aka3/9/9/4C4/4n4/9/9/4C4/9/4K4 w",
  "full_fen": "3aka3/9/9/4C4/4n4/9/9/4C4/9/4K4 w - - 0 1",
  "confidence": 0.97,
  "warnings": []
}
RULES

接入约定

  • 只在 status=accepted 时自动使用 fen。
  • review_required 表示应让用户检查或重新拍照。
  • 未拍到、被手遮挡或无法确认的格点按空位处理，并通过警告字段说明。
  • 临时 Key 仅用于测试；长期使用请联系微信 lgtqcn，39 元/年。
ENGINE PREVIEW

POST /v1/solutions

把已经确认的两字段或六字段中国象棋 FEN 转换成最佳着法和局面评分。time_ms 可省略，默认只搜索首选 3000 毫秒；单招最多 9000 毫秒。max_candidates 不填或填 auto 等同于 1，只有填 2 才搜索备选：首选最多 8000 毫秒，备选最多另用 1000 毫秒，总搜索预算最多 9000 毫秒。不可靠的备选不会返回。

curl -X POST https://xq.rakubank.com/v1/solutions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fen":"3aka3/9/9/4C4/4n4/9/9/4C4/9/4K4 w"}'
SOLUTION

适合直接展示的结果

图片直接解题使用 POST /v1/solve，表单为：image（必填文件）、side_to_move=auto、orientation=auto、movetime_ms=3000、max_candidates=auto。只有图片必填；后三类解题入口共享候选策略。/v1/solutions 使用 JSON 的 time_ms，不要与图片接口的 movetime_ms 混用。上传、识别、排队和传输不属于搜索预算。

{
  "status": "accepted",
  "best_move": {
    "iccs": "e6e8",
    "notation": "前炮进二"
  },
  "score": {
    "value": 2,
    "perspective": "red",
    "display": "红方 KO(2)"
  },
  "display_text": "前炮进二 红方 KO(2)"
}

本接口代码已开放；官方托管目前仅向维护者个人 Key 开放非商业验证。六分钟临时 Key 和普通识别 Key 无解题权限。