Automate Card Grading With AI via API – Step by Step

We offer a powerful set of computer vision tools tailored for collectors—including automated card identification, tagging, price search, and slab reading. Among the most popular are Card Condition and Card Grading, which automate sorting and grading by evaluating centering, corners, surface, and more, similar to PSA or Beckett standards.

In this guide, you’ll learn how to evaluate and pre-grade your entire card collection using our AI tools via API. No machine learning experience is needed—just a quick setup in our app and a simple API call to get started.

AI Card Grading as a New Standard

AI is becoming essential across industries, and collectibles are no exception. Trading & sports card enthusiasts are now using computer vision to assess condition, rarity, and market data with speed and consistency.

Ximilar was among the first teams to automate card grading with computer vision.

Ximilar was one of the first to launch automated card grading, working with experts and analyzing thousands of cards to develop tools that support—or even replace—traditional grading, especially for large collections.

Our models already cover TCGs like Pokémon, Yu-Gi-Oh!, and Star Wars, as well as sports cards from baseball and hockey to MMA and basketball—and we’re continually expanding to support more games, sports, and collector platforms.

ONE API TO RULE THEM ALL

AI That Understands Collectibles

Recognize, analyze & grade collectibles, find them in databases and marketplaces. Our API was built by collectors for collectors.

Explore & Try it now

Ximilar’s AI Card Evaluation Services & How to Test Them

Our computer vision tools for trading card evaluation range from quick condition checks to full grading, with varying complexity and API credit usage based on processing needs.

Interactive demos are available on the Visual AI for Collectibles page, but have limited results. Therefore, for the best results and access to the latest models, we recommend testing your images in the Ximilar App.

AI Card Grader

Endpoint: /v2/grade
A comprehensive grading API that evaluates centering, corners, edges, and surface, then returns both an overall grade and a detailed breakdown, plus card type, side, and autograph info. Designed to reflect grading standards used by PSA, Beckett, and CGC.

Output: Individual scores (corners, edges, surface, centering), overall average grade

Additional metadata: Orientation (front/back), type, autograph status

Use cases: High-accuracy grading, collector platforms, automated submissions

Bonus: Visual overlays for review or user display

Try demo Test in App

Card Condition

Endpoint: /v2/condition
Grading cards at scale can be time-consuming and expensive, and for large collections, it can become quite costly. But often, a quick overall condition assessment is all you need.

Card Condition is a lightweight service for fast card condition checks. It detects the largest card in an image and returns its condition based on your selected grading standard (mode): eBay, TCGplayer, Cardmarket, or Ximilar. This solution has lower processing demands and therefore uses half the API credits compared to full grading.

Output: Condition label (e.g., Near Mint, Moderately Played, Good, Damaged, etc.), bounding box of the card

Use cases: Marketplace listings, bulk condition checks, quick pre-grading

Try demo Test in App

Centering Analysis

Endpoint: /v2/centering
A dedicated service focused specifically on centering accuracy. It detects the card’s location and returns centering data, along with a visualization. Let’s see how it evaluates the 1986 O-Pee-Chee John Tonelli #132 hockey card:

Output: Centering metrics, front/back detection, card type (TCG/sport), autograph presence

Use cases: Visual verification, consistent centering scoring, app integrations

Bonus: Includes links to annotated images for easy inspection

Try demo Test in App

How to Connect to the AI Card Grader API

1. Setup in Ximilar App & Python

To use our API, start by registering in the Ximilar App to obtain your personal API authentication token.

In the app, you can configure your plan, estimate API credit usage, and test all solutions. The entire process, including a few steps in Python, is outlined in our First Steps in Ximilar App guide.

Get Started: First Steps Guide

2. Automate Card Grading via API

You can access the grading services using the following endpoints:

• /card-grader/v2/grade – AI Card Grader
• /card-grader/v2/condition – Card Condition
• /card-grader/v2/centering – Card Centering

Card Grading API Request

Below is a sample curl request using the /v2/grade endpoint. Be sure to replace YOUR_API_TOKEN with your actual API token and provide the _url of your image.

curl --url https://api.ximilar.com/card-grader/v2/grade
 --request POST 
 --header "Content-Type: application/json"
 --header "Authorization: Token YOUR_API_TOKEN" 
 --data '{
  "records": [
    {
      "_url": "https://www.sportsnet.ca/wp-content/uploads/2017/09/NHL-21-Era-Tonelli.jpg"
    }
  ]
}'

Tip: When you upload an image to test the solutions in the Ximilar App using the drag-and-drop forms, the app will display the full API requests and the JSON responses below the results.

Key Fields in the Card Grading API Response

The response returns the full breakdown of grading data, including location of the card, grades for each corner and edge, centering analysis, surface condition, and the overall grade, shown as both a number and a descriptive label:

"grades": {
  "corners": 4.5,
  "edges": 7.5,
  "surface": 6,
  "centering": 8,
  "final": 6.5,
  "condition": "Excellent"
}

Result Explanation

Autograph: Indicates the presence of a signature

Corners / Edges – Each corner and edge is graded individually, revealing damage or wear at specific card zones.

Centering – Includes both visual offsets (left/right, top/bottom ratios) and a numeric centering grade.

Surface – Evaluates the card’s surface quality (e.g., scratches or dirt).

Final (grade) – Represents the overall average grade across all factors.

_tags – Additional metadata about the card include:

Condition: Text label such as “Excellent” based on the overall grade

Category: TCG or sports card

Side: Whether the front or back is shown

Our card grading system accepts a maximum of two images per request—typically the front and back of a card. If you need to process a batch of images, you’ll need to write a script that iterates through them one pair at a time. If you need help setting this up, feel free to contact us.

Card Condition API Request

To use this endpoint, you need to specify your preferred grading standard with the mode parameter. In this example, I will set the mode to eBay to get a numeric score and label based on the eBay condition scale:

curl --url https://api.ximilar.com/card-grader/v2/condition
  --request POST
  --header "Content-Type: application/json"
  --header "Authorization: Token YOUR_API_TOKEN"
  --data '{
    "records": [
      {
        "_url": "https://www.sportsnet.ca/wp-content/uploads/2017/09/NHL-21-Era-Tonelli.jpg"
      }
    ],
    "mode": "ebay"
  }'

Card Condition can be used as a standalone check or as the first step in a larger image-processing pipeline. For example, you might assess the condition of 500 cards, then send only the top ones for full grading. Our solutions are designed to work together and can be chained in sequence using Flows.

How the Card Condition API Response Looks

The response returns the detected card and its overall condition, scored according to the selected scale. It also provides classification details, bounding box coordinates, and metadata such as card side. Below is a shortened example to illustrate the structure:

{
  "Condition": [
    {
      "label": "Very Good",
      "scale_value": 2,
      "max_scale_value": 4,
      "mode": "ebay"
    }
  ],
  "Category": [
    { "name": "Card/Sport Card" }
  ],
  "bound_box": [211, 95, 793, 906]
}

Response Explanation

Label: A text label for the condition (e.g., “Very Good”).

Scale value: A numeric value representing the label (e.g., 2 for “Very Good”).

Value: A precise floating-point score for the condition (e.g., 3.23748).

Max scale value: The highest possible value on the selected grading scale (e.g., 4 for eBay).

Mode: The grading scale used for evaluation (e.g., “eBay”).

Category / Top category: Classification of the card (e.g., “Sport Card” or “TCG”).

Bound box: The pixel coordinates of the detected card within the image.

URL: The evaluated source image.

Status: Request status and technical information (e.g., request ID, code 200 OK).

Card Centering API

Requests to the /centering endpoint follow the same structure as grading. The system analyzes the card’s alignment and returns ratios like “59/41” (left/right) and “40/60” (top/bottom), a numeric centering grade, bounding boxes, offset values, and metadata such as side and category.

Here’s a shortened example of the response:

{
  "grades": {
    "centering": 8
  },
  "card": [
    {
      "centering": {
        "left/right": "59/41",
        "top/bottom": "40/60",
        "grade": 8,
        "offsets": [0.0573, 0.0274, 0.0401, 0.0417],
        "bound_box": [31, 21, 529, 739]
      },
      "_tags": {
        "Side": [{ "name": "Front", "prob": 0.98951 }],
        "Autograph": [{ "name": "No", "prob": 0.90812 }],
        "Category": [{ "name": "Card/Sport Card", "prob": 0.99622 }]
...

Need Help with the Setup? We’re Here for You

Whether you’re building an app for TCG fans or a marketplace for sports card collectors, Ximilar’s Card Grading API delivers the flexibility and accuracy to automate your entire image-processing workflow. Our solutions work seamlessly with both professional images and user-generated photos, and are trusted by major players in the industry.

Start by testing your images in the Ximilar App and exploring the available endpoints that can be integrated into your system. Need fine-tuning or setup advice? Just reach out—we’re happy to help.