How to Scan and Identify Trading Cards With Ximilar AI
A guide for collectors and businesses looking to streamline their card-processing workflow with AI.
In the world of trading card scanning and seller tools, efficiency is crucial. Apps like CollX or Ludex identify a single card from a phone photo, for hobby collectors as well as those who earn money selling trading cards. Ximilar offers the same kind of recognition as API solutions for businesses that want to integrate visual search and image recognition into their own apps or websites, with the option of customisation.
Today, I’d like to introduce a solution for physical stores and warehouses that need to process their card collections quickly with a document scanner, such as the Ricoh (formerly Fujitsu) fi-8170. This tutorial is tailored for shop owners who handle large volumes of card images. We’ve written a simple Python 3 script that identifies cards and can assess their condition or grade them. It also identifies comic books and reads slab labels from graders such as PSA or Beckett. The script outputs a CSV file that you can import into Google Sheets or Microsoft Excel. With a few changes, it can also feed your Shopify store or other seller tools, for example for eBay listings. Let’s dive in and see how it can streamline your card-processing workflow!
Capabilities of Our AI Solution for Sports Cards and TCGs
Trading Card Games
In my post on how to identify sports cards with AI, I wrote about our REST API for identifying TCGs, sports cards and comic book covers. The TCG identification service supports more than 20 trading card games, including Pokémon, Magic: The Gathering, Yu-Gi-Oh!, One Piece, Lorcana, Flesh and Blood and Digimon. For some games, it can also identify the language version of the card or tell whether it is a foil/holographic card, and the results include TCGplayer links or IDs. You can try it on our collectibles recognition page.
Sports Cards
For sports cards, we identify baseball, basketball, football, hockey, soccer and MMA cards, including parallel and reprint versions. You get the best match as well as alternative candidates to choose from. Cards that aren’t in our database yet can be identified with Magic AI.
If the cards are in slabs from major grading companies such as PSA, Beckett, CGC, TAG, SGC or ACE, the system identifies the graded card and returns the slab company, grade and certificate number.
All Under One API
All of this runs through one API, so you can identify whole collections in bulk, in several languages. I believe that Ximilar Collectibles Recognition services are the most accurate solutions on the market today. For card dealers, collectors and companies, it means you can run your own card scanning workflow instead of depending on third-party apps and services such as CollX, Kronozio or Card Dealer Pro.
Whether you buy, scan, search or sell cards in bulk, your inventory and data stay in your own systems, and we can adapt the models to your needs.
How to Scan and Identify Trading Cards With AI
Step 1 – Run The Cards Through The Scanner
Enough talk! Let’s identify your cards in bulk. First, you’ll need a folder with images of your cards. For testing, I’ve selected a small set of MTG and Pokémon cards. You can feed cards into your scanner one by one, or cards in top loaders with an autoloader such as the Laskis AutoLoader TL. Many card shops use the Ricoh (formerly Fujitsu) fi-8170 scanner, which scans both sides of a card in one pass.
For our purposes, we only need the front side of the cards. To avoid unnecessary costs, set your scanner to save only the fronts, or pick the fronts with the --select_images option in Step 4. Ricoh scanners can name scan files, for example, 19032024-0001.jpg or 19032024-FRONT-0001.jpg, and you can set the naming format in PaperStream Capture. This video by MaxWaxPax shows how to set up the scanner for cards:
I recommend using settings similar to those in the video and creating separate profiles for sideways and top-to-bottom card scanning. Ideally, set up the scanner to save only the fronts of the cards, or to add “front” or “back” to the file names. If you already have an unstructured collection of card images, our AI Recognition of Collectibles can tell the fronts from the backs automatically.
Step 2 – Sign Up To The Ximilar App
Next, you’ll need an account in our App. Sign up with your personal or company email to get your unique API token, and save it somewhere safe. To use the collectibles recognition via API, you’ll need at least a Business plan. You can copy the token and buy the plan in the App settings in a matter of minutes.

Step 3 – Installing Python 3
Don’t want to install Python or use a terminal? Cardloader.ai, our free, open-source trading card scanner software for Windows, macOS and Linux, does the same job in a desktop app. It runs the fi-8170 directly and uses the same Ximilar API, or a free local model offline.
Before running the script, make sure you have Python 3 installed. Some operating systems already include it, and the script needs Python 3.6 or newer. If you’re unsure, follow the Real Python guide to installing Python, with steps for Windows, macOS and Linux:

To check the installation, run this command in your terminal (macOS), shell (Linux) or command line (Windows). Here’s mine on a Mac:
michallukac@Michals-MacBook ~ % python --version && pip --version
If you haven’t used a terminal before, read the Django Girls introduction to the command line, or watch a short video for Windows or macOS. The output should look similar to mine:
Python 3.9.18
pip 23.1 from /Users/michallukac/env/devel/lib/python3.9/site-packages/pip (python 3.9)
Next, install the requests library with pip. The other library the script uses, argparse, comes with Python:
pip install --upgrade requests
If everything passes, you’re ready to run the script on your folder of card images.
Step 4 – Running The Script On Trading Card Games
Running the script is simple. Download process_card_scans.py from our public GitLab repository:
Put the script next to the folder with your card images or scans (here tcgscans) and run this command in the terminal:
python process_card_scans.py --folder tcgscans --api_key YOURAPIKEY --collectible tcg --output results.csv --select_images all
Instead of passing --api_key, you can also set your token in the XIMILAR_API_KEY environment variable. After you press Enter, the script processes every image in the tcgscans folder (--select_images all) and shows a progress bar. It saves the results to the output CSV file every 10 images, so you can stop it at any time. When you run the same command again, it skips the images that are already in the file. To retry the ones that failed, add --process_error.

These options change what the script does:
| Option | What it does |
|---|---|
--collectible | tcg, sport, comics or slab identifies the items. grade or condition only grades the cards, without identification. |
--select_images | Which images to process: all, odd or even (by the number at the end of the file name, e.g. 0001 in 19032024-0001.jpg), or front or back (by that word in the file name). |
--alternative | If there is no best match, uses the first alternative candidate. |
--condition | Adds the card condition. |
--grade | Adds an AI grade for corners, edges, surface and centering, plus a final grade. |
--slab_grade | For cards in slabs, adds the grading company and grade from the label. |
--num_workers | Number of images processed in parallel (default 1). |
--process_error | On a repeated run, processes the images that failed before. |
--output | Name of the CSV file (default output.csv). |
Each card identification (TCG, sports card or comic) uses 10 credits from your Ximilar account, and a slab 15. The condition adds 50 credits and the grade 100. Our App lets you watch your credit consumption closely under Reports. The Business 100K plan includes 100,000 credits a month, enough to identify 10,000 raw cards. If you need to identify millions of cards a month or your entire collection at once, reach out to us, and we can offer you a bulk discount.

Step 5 – Analysing The CSV File
Now you have a CSV file named results.csv. It contains these fields: filename (name of the image in the folder), status (ok or error), side (front or back), subcategory, full_name, name, year, card_number, and further fields such as set, set_code or series.
The output format of the CSV depends on whether you identify sports cards, TCG cards, comics or slabs. Here is the CSV file in Visual Studio Code:

The script separates the columns with semicolons, so set the separator to a semicolon when you import the file into Google Sheets or Microsoft Excel. Then you can edit it as needed, generate printable checklists, or add the columns to your Shopify product files or eBay listings.
To add the card condition or a grade, use the --condition or --grade option. For example, if your scanner names the images 0001.jpg, 0002.jpg, 0003.jpg and so on, with the fronts on odd numbers, this command processes only the odd-numbered images (0001.jpg, 0003.jpg, …), identifies the cards (name, card number, etc.) and adds their condition (very good, excellent, etc.):
python process_card_scans.py --folder sportsfolder --api_key YOUR_API_KEY --collectible sport --output sport.csv --select_images odd --alternative --condition
Conclusion
With this script and the Ximilar API, you can identify and document a whole box of trading cards in one run, from the scanner to a spreadsheet. If you’d rather not run scripts, Cardloader.ai does the same in a desktop app. I hope this guide helps you streamline your trading card workflow. Happy collecting, whether it’s baseball or Pokémon cards!
Tags & Themes
Related Articles
Cardstream.ai: Open-Source Card Scanner for Live Streams
An open-source card scanner for live streams. Cardstream.ai identifies TCGs like Pokémon and sports cards in real time from your video.
Recognize Every Palworld TCG Card in English and Japanese
Ximilar’s card AI now handles Palworld card recognition in English and Japanese, from a single scan. Test it in the App, via API or the demo.
Instance Segmentation on Click: Build Your Own AI Model
Train your own instance segmentation model with Ximilar’s no-code computer vision platform – from polygon annotation to a deployed API.