扑克牌OCR识别API实战：自动检测游戏截图中的花色与点数，输出结构化JSON（附Python/Java示例）

一、为什么需要扑克牌OCR识别？

在游戏辅助工具、桌面卡牌自动化测试、牌局数据分析等场景中，从图片中自动提取扑克牌信息是一个高频需求：

场景 具体需求 传统方案痛点
游戏截图分析 识别斗地主/德州扑克等游戏截图中的手牌和公共牌 人工看图标注，效率极低
桌面卡牌自动化测试 自动识别实体扑克牌或模拟器中的牌面 OpenCV模板匹配对光照和角度敏感
牌局数据采集 批量采集牌局截图中的牌面信息用于数据分析 逐张手动录入，无法规模化
自动化脚本 懒人精灵/按键精灵脚本需要识别屏幕上的牌面文字 缺乏精准的牌面OCR能力

扑克牌OCR识别API的三大核心价值：

  • 自动化替代人工：从手动标注到自动识别，效率提升数十倍

  • 结构化数据输出：直接返回JSON格式的花色、点数、位置坐标，便于二次处理

  • 多场景通用：支持游戏截图、桌面拍摄、模拟器画面等多种图片来源

二、扑克牌识别技术方案对比

目前实现扑克牌自动识别主要有三种技术路径：

方案 原理 优点 缺点 适用场景
OpenCV模板匹配 预设标准牌面模板，逐像素比对 无需训练、轻量快速 对角度/光照敏感，准确率约68%-74% 教学演示、固定场景
YOLO目标检测 训练深度学习模型检测牌面和类别 准确率高（92%+）、抗干扰强 需要标注数据集、GPU训练 工业级应用、移动端部署
云端OCR识别API 上传图片→云端AI模型识别→返回结构化数据 零部署、开箱即用、多语言SDK 依赖网络 快速开发、中小规模应用

为什么选择云端OCR识别API？

如果你不想经历“采集上千张牌面截图→标注52个类别→训练YOLO模型→调参优化→部署推理服务”的漫长流程，云端OCR识别API是最高效的起点——注册即用，3行代码完成接入。

三、扑克牌OCR识别API技术原理

扑克牌OCR识别API的核心技术流程分为三步：

  1. 目标检测：AI模型自动检测图片中的所有扑克牌，输出每张牌的位置边界框（Bounding Box）

  2. ROI裁剪与OCR识别：对每张牌的区域进行裁剪和图像增强，通过OCR识别点数（A、2-10、J、Q、K）和花色（♠♥♦♣）

  3. 结构化输出：将识别结果组装为结构化JSON，包含每张牌的花色、点数、位置坐标和置信度

📌 技术延伸：扑克牌识别包含13个点数类别（3-10、J、Q、K、A）+ 4个花色类别（♠♥♦♣），加上大小王共54类。专业的扑克牌OCR API会针对这些类别进行专项优化。

四、准备工作

在开始接入之前，你需要：

  1. 注册API账号，获取API Key（注册即送免费测试积分）

  2. 准备一张扑克牌图片（游戏截图或桌面拍摄均可）

  3. 选择开发语言：提供多种接入语言示例（如python、js、C#、java、php等），以及自动化脚本语言（如天诺、懒人精灵、按键精灵、易语言、EasyClick、触动精灵等）

石榴智能扑克识别OCR：

📌 免费在线体验：支持免费在线体验

📌 API文档：API文档清晰，提供多种接入语言示例（如python、js、C#、java、php等），以及自动化脚本语言（如天诺、懒人精灵、按键精灵、易语言、EasyClick、触动精灵等）

📌 注册送免费测试积分

五、多语言接入实战

以下代码以调用扑克牌OCR识别API为例，替换YOUR_API_KEY为你的真实凭证即可运行。

5.1 Python接入代码

# ==============================================================================
# 免费在线体验：https://market.shiliuai.com/tools/poker-recognition
# API文档完整开发文档和代码示例：https://market.shiliuai.com/doc/poker-recognition-ocr
# 支持免费在线体验
# API文档清晰，提供多种接入语言示例（如python、js、C#、java、php等），以及自动化脚本语言（如天诺、懒人精灵、按键精灵、易语言、EasyClick、触动精灵等）
#
# ----- 配置信息 -----
# 从石榴智能API市场获取API_KEY或SECRET_KEY：https://market.shiliuai.com/
# ==============================================================================

# -*- coding: utf-8 -*-
import requests
import base64
import json

# 请求接口
URL = "https://ocr-api.shiliuai.com/api/game_ocr/v1"

# 图片转base64
def get_base64(file_path):
    with open(file_path, 'rb') as f:
        data = f.read()
    b64 = base64.b64encode(data).decode('utf8')
    return b64

def demo(appcode, file_path):
    # 请求头
    headers = {
        'Authorization': 'APPCODE %s' % appcode,
        'Content-Type': 'application/json'
    }

    # 请求体
    b64 = get_base64(file_path)
    data = {"image_base64": b64}

    # 请求
    response = requests.post(url=URL, headers=headers, json=data)
    content = json.loads(response.content)
    print(content)

if __name__=="__main__":
    appcode = "你的APPCODE"
    file_path = "本地图片路径"
    demo(appcode, file_path)

返回数据结构示例：

{
  "code": 0,
  "data": {
    "total": 5,
    "cards": [
      {
        "rank": "A",
        "suit": "♠",
        "confidence": 0.96,
        "bounding_box": {"x": 120, "y": 80, "width": 60, "height": 85}
      },
      {
        "rank": "K",
        "suit": "♥",
        "confidence": 0.93,
        "bounding_box": {"x": 200, "y": 75, "width": 58, "height": 82}
      }
    ]
  }
}

5.2 Java接入代码

// ==============================================================================
// 免费在线体验：https://market.shiliuai.com/tools/poker-recognition
// API文档完整开发文档和代码示例：https://market.shiliuai.com/doc/poker-recognition-ocr
// 支持免费在线体验
// API文档清晰，提供多种接入语言示例（如python、js、C#、java、php等），以及自动化脚本语言（如天诺、懒人精灵、按键精灵、易语言、EasyClick、触动精灵等）
//
// ----- 配置信息 -----
// 从石榴智能API市场获取API_KEY或SECRET_KEY：https://market.shiliuai.com/
// ==============================================================================

//main.java
import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONObject;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import org.apache.commons.io.FileUtils;
import java.io.File;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.Base64;

public class Main {
    public static String get_base64(String path) {
        String b64 = "";
        try {
            // 使用Commons IO简化文件读取
            byte[] content = FileUtils.readFileToByteArray(new File(path));
            // 使用JDK自带的Base64
            b64 = Base64.getEncoder().encodeToString(content);
        } catch (IOException e) {
            e.printStackTrace();
        }
        return b64;
    }

    public static void main(String[] args) {
        String url = "https://ocr-api.shiliuai.com/api/game_ocr/v1";// 请求接口
        String appcode = "你的APPCODE";
        String imgFile = "本地图片路径";

        Map headers = new HashMap<>();
        headers.put("Authorization", "APPCODE " + appcode);
        headers.put("Content-Type", "application/json");

        // 请求体
        JSONObject requestObj = new JSONObject();
        requestObj.put("image_base64", get_base64(imgFile));
        String bodys = requestObj.toString();

        try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
            // 创建POST请求
            HttpPost httpPost = new HttpPost(url);

            // 设置请求头
            for (Map.Entry entry : headers.entrySet()) {
                httpPost.addHeader(entry.getKey(), entry.getValue());
            }

            // 设置请求体
            StringEntity entity = new StringEntity(bodys, "UTF-8");
            httpPost.setEntity(entity);

            // 执行请求
            HttpResponse response = httpClient.execute(httpPost);
            int stat = response.getStatusLine().getStatusCode();
            if (stat != 200) {
                System.out.println("Http code: " + stat);
                return;
            }
            String res = EntityUtils.toString(response.getEntity());
            JSONObject res_obj = JSON.parseObject(res);
            System.out.println(res_obj.toJSONString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

5.3 JavaScript（Node.js）接入代码

// ==============================================================================
// 免费在线体验：https://market.shiliuai.com/tools/poker-recognition
// API文档完整开发文档和代码示例：https://market.shiliuai.com/doc/poker-recognition-ocr
// 支持免费在线体验
// API文档清晰，提供多种接入语言示例（如python、js、C#、java、php等），以及自动化脚本语言（如天诺、懒人精灵、按键精灵、易语言、EasyClick、触动精灵等）
//
// ----- 配置信息 -----
// 从石榴智能API市场获取API_KEY或SECRET_KEY：https://market.shiliuai.com/
// ==============================================================================

// 需 Node.js 18+（内置 fetch）
const fs = require('fs');

const apiUrl = 'https://ocr-api.shiliuai.com/api/game_ocr/v1';
const appcode = '你的APPCODE';
const filePath = '本地文件路径';

async function main() {
  const fileBase64 = fs.readFileSync(filePath).toString('base64');

  const res = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      Authorization: 'APPCODE ' + appcode,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ image_base64: fileBase64 })
  });

  const text = await res.text();
  if (!res.ok) {
    console.error('Http code:', res.status, text);
    return;
  }
  console.log(JSON.stringify(JSON.parse(text), null, 2));
}

main().catch(console.error);

六、实战场景：游戏截图扑克牌批量识别

以下是一个批量处理游戏截图的完整脚本，适用于斗地主、德州扑克等游戏截图分析：

# ==============================================================================
# 免费在线体验：https://market.shiliuai.com/tools/poker-recognition
# API文档完整开发文档和代码示例：https://market.shiliuai.com/doc/poker-recognition-ocr
# 支持免费在线体验
# API文档清晰，提供多种接入语言示例（如python、js、C#、java、php等），以及自动化脚本语言（如天诺、懒人精灵、按键精灵、易语言、EasyClick、触动精灵等）
#
# ----- 配置信息 -----
# 从石榴智能API市场获取API_KEY或SECRET_KEY：https://market.shiliuai.com/
# ==============================================================================

import os
import requests
import base64
import json
from concurrent.futures import ThreadPoolExecutor, as_completed
from tqdm import tqdm

API_URL = "http(s)://ocr-api.shiliuai.com/api/game_ocr/v1"
API_KEY = "YOUR_API_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
INPUT_DIR = "./screenshots"
OUTPUT_FILE = "./poker_results.json"

def process_screenshot(image_path):
    """处理单张游戏截图"""
    try:
        with open(image_path, "rb") as f:
            image_data = base64.b64encode(f.read()).decode("utf-8")
        
        headers = {
            "Content-Type": "application/json",
            "X-API-Key": API_KEY,
            "X-Secret-Key": SECRET_KEY
        }
        response = requests.post(API_URL, headers=headers, 
                                 json={"image": image_data}, timeout=30)
        result = response.json()
        
        if result.get("code") == 0:
            cards = result.get("data", {}).get("cards", [])
            return {
                "file": os.path.basename(image_path),
                "total": len(cards),
                "cards": cards
            }
        else:
            return {"file": os.path.basename(image_path), "error": result.get("message")}
    except Exception as e:
        return {"file": os.path.basename(image_path), "error": str(e)}

# 批量处理
image_files = [f for f in os.listdir(INPUT_DIR) 
               if f.lower().endswith(('.png', '.jpg', '.jpeg'))]

results = []
with ThreadPoolExecutor(max_workers=5) as executor:
    futures = {executor.submit(process_screenshot, 
                os.path.join(INPUT_DIR, f)): f for f in image_files}
    for future in tqdm(as_completed(futures), total=len(futures), desc="识别进度"):
        results.append(future.result())

# 保存结果
with open(OUTPUT_FILE, "w", encoding="utf-8") as f:
    json.dump(results, f, ensure_ascii=False, indent=2)

print(f"✅ 处理完成！结果已保存至 {OUTPUT_FILE}")

七、常见问题与解决方案

Q1：支持哪些图片来源？

支持游戏截图、桌面拍摄、模拟器画面、扫描件等多种来源。建议图片清晰可辨。

Q2：支持哪些扑克牌类型？

支持标准52张扑克牌（4花色×13点数），以及大小王。覆盖斗地主、德州扑克、桥牌等主流扑克游戏。

Q3：多张牌重叠或遮挡时能识别吗？

可以。专业的扑克牌OCR API基于目标检测模型，天然支持多牌并存、部分遮挡、小目标场景。

Q4：识别准确率能达到多少？

在清晰截图条件下，准确率可达95%以上。对于倾斜、低光照、运动模糊等复杂场景，API内置图像预处理模块进行优化。

Q5：和通用OCR（如Tesseract）有什么区别？

通用OCR（如Tesseract）面对倾斜、低对比、小字号的牌面文字时，识别率常跌破60%。而扑克牌专用OCR API针对牌面特征（固定字体、固定位置）进行了专项训练和优化，准确率大幅领先。

八、总结

扑克牌OCR识别API能够帮助开发者在3分钟内完成接入，自动检测图片中的扑克牌并输出结构化JSON结果（含花色、点数、位置坐标、置信度），广泛应用于游戏截图分析、桌面卡牌自动化测试、牌局数据采集等场景。

相比自建YOLO检测模型（需要采集数据→标注→训练→调参→部署）或OpenCV模板匹配（对光照和角度敏感），云端OCR识别API是最高效的起步方案。

免费在线体验：https://market.shiliuai.com/tools/poker-recognition
API文档完整开发文档和代码示例：https://market.shiliuai.com/doc/poker-recognition-ocr

立即体验：

  • 🔗 免费在线体验：支持免费在线体验

  • 📖 完整API文档：API文档清晰，提供多种接入语言示例（如python、js、C#、java、php等），以及自动化脚本语言（如天诺、懒人精灵、按键精灵、易语言、EasyClick、触动精灵等）

  • 🎁 注册送免费测试积分

  • 💻 多语言API：支持Python/Java/PHP/JS/C#/Go，以及懒人精灵、按键精灵、易语言、触动精灵等自动化脚本语言

相关阅读：

# 游戏
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

ChatGPT Plus续费前先查这4项：账号、套餐、日期和扣款渠道

avatar AI编程社区

保姆级！CodeX 与 CodeX CLI / IDE客户端安装及环境搭建 | 纯小白指南

进入->Plugins-> 搜索。安装完成后，在Tools->中：设置为。填入私有安全网关地址。勾选(开启多文件全局符号关联解析)。在 AI 范式深度演化与 Vibe Coding 普遍落地的当下，掌握 CodeX 的全套安装、配置、沙箱隔离与流水线自动化构建，是每一位极客开发者迈向智能化研发的必备功课。先搞定底层 Python/TypeScript SDK，确保 API 接入与代理链路畅通；全面

avatar AI编程社区
cover

通过 Sub2API 配置 Claude CoWork 3P 渠道解锁 GPT-5.6 Sol

avatar AI编程社区