Pokemon Card Scanner - Identify Cards from a Photo

Identify a trading card from a photo in under 400 ms. Visual recognition that works where OCR fails: glare, sleeves, holo foil, worn cards and partially obscured text.

原始信息汇总

数据集概述

该数据集对应一个基于视觉识别的宝可梦卡牌扫描与识别API，旨在通过照片快速识别宝可梦卡牌并返回结构化信息。

• 核心功能：上传卡牌照片，在约50毫秒内完成识别，端到端延迟通常低于400毫秒，返回匹配的卡牌名称、系列代码、收集编号、稀有度及参考图片。
• 识别原理：采用视觉嵌入与最近邻匹配，而非传统OCR。文本仅用于对候选结果进行重排序，因此能有效应对卡牌反光、卡套、磨损、角度倾斜及部分遮挡等情况。
• 支持范围：仅支持英文版宝可梦卡牌，目录包含20,406张卡牌，并随新系列发布动态更新。

输入与输出

• 输入方式：支持三种图片提交方式——multipart/form-data 的 image 字段（推荐）、application/json 的 image_base64 字段（接受 data:image/...;base64, 前缀）及 image_url 字段（服务端抓取）。图片最大12 MB（解码后），支持JPEG、PNG、WebP格式。
• 输出内容：返回按匹配分数排序的候选卡牌列表，每张卡牌包含 card_id、名称、系列ID、系列代码、卡牌编号、稀有度、参考图片URL及匹配分数。同时提供 confidence（校准置信度）、auto_accept（是否可自动接受顶级匹配）、top_score、margin（顶级与次级的分数差距）及 match_path（匹配路径，如 visual 或 visual+number）。

关键特性

• 不确定性处理：API不仅返回识别结果，还明确告知结果的可信度。auto_accept: true 表示顶级匹配既强且明显领先，可安全自动应用；confidence: high 但 auto_accept: false 表示存在高度相似的“近似孪生”卡牌（如跨系列同图重印），需用户选择；margin 可为此提供决策依据。
• 提示参数：用户可传递 hint_set_code 和 hint_card_number（如已有OCR结果或用户已知系列）来打破同图重印的平局。错误的提示不会导致图像匹配未发现的卡牌出现，安全性有保障。
• 非OCR优势：针对全息箔片反光、微型收集编号、卡套或顶部加载器、磨损老卡及手持角度拍摄等情况，识别稳定性远超基于文本的扫描方案。

API信息

• 端点：共3个——POST /v1/recognize（识别，消耗1次扫描配额）、GET /v1/meta/index（目录版本与卡牌数量，免费）、GET /v1/meta/health（存活检查，免费且无需认证）。
• 配额与限流：配额按月计算（UTC日历月，每月1日重置），每个计划有硬性上限，超额不会自动计费。仅成功识别消耗配额；验证失败（422）、认证失败（401/403）、限流拒绝（429）及引擎错误（503/504）不消耗配额。响应头包含 X-Quota-Limit、X-Quota-Remaining、X-RateLimit-Limit 等，用于监控使用情况。
• 服务级别：服务等级100%，平均延迟303毫秒，接口流行度评分8.5。

适用场景

• 收藏与组合管理应用的“扫描添加”功能
• 卡牌商店和卖家的批量入库与库存管理
• 评级提交工具在提交前确认卡牌身份
• 市场列表工具自动填写系列、编号和稀有度
• Discord和Telegram机器人响应“这是什么卡？”查询

订阅计划

计划	月扫描量	每分钟限流	顶级候选数 (top_n)
Basic	2,500	60	5
Pro	10,000	180	10
Ultra	30,000	600	20
Mega	75,000	1,200	20

所有付费计划均允许商业用途，可用于订阅方拥有的任意数量应用；但转售原始识别服务或构建直接竞争的卡牌识别API需单独许可。超过每月75,000次扫描可通过邮件联系获得合同定价。

数据与限制

• 语言与目录：仅覆盖英文宝可梦卡牌；其他游戏（如日文宝可梦、万智牌等）不在此索引中，非支持卡牌会返回低置信度结果而非错误。
• 分数可比性：score 为余弦相似度，仅在单次响应内可比；不同 index_version 间不可比较。缓存结果时应同时记录版本号。
• 同图重印：同插画的不同系列卡牌无法仅凭图像区分，这是固有局限，通过 auto_accept: false 及提示参数解决。
• 图片要求：卡牌需为画面主体；杂乱背景可能导致检测失败，此时会回退为卡牌宽高比的中心裁剪并报告低置信度，绝不给出基于背景的自信猜测。
• 隐私：用户提交的图片会被保留用于提升识别准确性，存储为私有，不会发布、转售或与其他客户共享，仅与引擎产生的匹配结果关联。可通过邮件申请删除图片或退出保留。