Identify a card from a photo

A photograph goes in and a ranked list comes out. Never a single answer: reprints and regional twins share their artwork, so an exact call from the image alone is not available to us and would not be available to anyone. What the endpoint returns instead is what it actually knows — the candidates, how far each one is, and whether the top of the list is far enough clear of the rest to act on without asking a human.

How it works

Every catalogue image is reduced to a 64-byte perceptual signature — a DCT signature of its low frequencies plus a gradient signature — and your photograph is reduced the same way. The comparison is a Hamming distance across the whole index, which is a linear scan and costs under a millisecond.

The photograph does not need to be a tight crop. Before hashing, the card is looked for as a quadrilateral in the frame and each candidate quadrilateral is straightened into the canonical portrait crop; those hypotheses compete with a set of concentric centre crops, and the one that actually matches the catalogue wins on distance. A quadrilateral that grabbed the table instead of the card lands about three times farther away and simply loses.

Reading the decision

data.id is populated only on match. On ambiguous it is null on purpose: a client that reads it without looking at decision should break immediately and visibly rather than quietly hand over the wrong printing.

Body fields

Headers

Example request

curl -s -X POST "https://api.pokemontcgapi.com/v1/vision/identify" \
  -H "X-Api-Key: $PTCG_API_KEY" \
  -F "[email protected]" \
  -F "top_k=3"

Example response

200 OK · Cache-Control: private, no-store

{
  "data": {
    "decision": "ambiguous",
    "id": null,
    "candidates": [
      {
        "id": "bs-4",
        "name": "Charizard",
        "number": "4",
        "set": { "code": "bs", "name": "Base Set", "print_region": "WEST" },
        "rarity": "Rare Holo",
        "image_url": "https://img.pokemontcgapi.com/cards/bs/4-normal.webp",
        "distance": 31,
        "confidence": 0.818
      },
      {
        "id": "b2-4",
        "name": "Charizard",
        "number": "4",
        "set": { "code": "b2", "name": "Base Set 2", "print_region": "WEST" },
        "rarity": "Rare Holo",
        "image_url": "https://img.pokemontcgapi.com/cards/b2/4-normal.webp",
        "distance": 38,
        "confidence": 0.776
      }
    ]
  },
  "meta": {
    "count": 2,
    "cards_indexed": 51983,
    "index_built_at": "2026-08-27T04:10:22Z",
    "signature_version": 1,
    "regions_detected": 2,
    "hypotheses_tried": 8,
    "elapsed_ms": 74
  }
}

Errors

Every error body carries error.code, error.message and error.request_id. Switch on the code, never on the message.

The full taxonomy, with what to do about each code, is on the errors page.

Two candidates, one illustration

The example above is the normal case rather than an edge case. Base Set Charizard and its Base Set 2 reprint are the same illustration on the same layout; the seven bits between them are printing noise, not a difference the camera can see. Any scanner that picks one of the two silently is wrong about half the time, and it is wrong on precisely the cards people care most about.

The two ways out are both in your hands: pass set or region when your workflow knows them — someone inventorying a pack they just opened does — or present both and take one tap. What the API will not do is guess and call it certainty.