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.

Michal Lukáč, Ximilar
Michal Lukáč 05.08.2024
9 minutes of reading
Learn how to streamline your card processing using artificial intelligence. This guide covers scanner setup, running the script, and results.

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.

Sign in to the Ximilar App to see and copy your authorisation token.
Sign in to the Ximilar App to see and copy your authorisation token.

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:

Installing Python on Windows and macOS takes only a few clicks.
Installing Python on Windows and macOS takes only a few clicks.

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.

Running the script on a folder of trading card scans.
Running the script on a folder of trading card scans.

These options change what the script does:

OptionWhat it does
--collectibletcg, sport, comics or slab identifies the items. grade or condition only grades the cards, without identification.
--select_imagesWhich 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).
--alternativeIf there is no best match, uses the first alternative candidate.
--conditionAdds the card condition.
--gradeAdds an AI grade for corners, edges, surface and centering, plus a final grade.
--slab_gradeFor cards in slabs, adds the grading company and grade from the label.
--num_workersNumber of images processed in parallel (default 1).
--process_errorOn a repeated run, processes the images that failed before.
--outputName 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.

API credit consumption per operation in the Ximilar App.
Visualisation of API credit consumption per image processing operation in the Ximilar App.

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:

CSV file with trading card identification results in Visual Studio Code.
My 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!

Michal Lukáč, Ximilar

Michal Lukáč

CEO, ML Expert & Co-founder

Michal is a CEO of Ximilar and a machine learning expert focusing mainly on image recognition, visual search and computer vision. He is interested in science, loves reading books and Brazilian Jiu-Jitsu.

Tags & Themes

Related Articles

An open-source card scanner for live streams. Cardstream identifies TCGs like Pokémon and sports cards in real time from your videos.

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.

Read more October 2026
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.

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.

Read more October 2026
Train your own instance segmentation model with Ximilar’s no-code computer vision platform – from polygon annotation to a deployed API.

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.

Read more September 2026