---
title: "Identify Card from Image"
method: POST
path: "/v1/cards/image-match"
tags: ["Image Search"]
---

# Identify Card from Image

`POST /v1/cards/image-match`

**AI-powered upgrade to [`POST /v1/cards/image-search`](#operation/image_search_v1_cards_image_search_post).** Where image-search returns a ranked list of visually similar candidates, image-match uses AI to pick the single `best_match` card and resolve its color/finish variant (e.g. Base vs. Silver vs. Red).

Returns `best_match` (null when the AI isn't confident) plus the `candidates` it considered, so callers can fall back to the ranked list when the match is uncertain.

## Request body

- ImageMatchRequest — Request model for the image-match endpoint.
  - `image_url` string, nullable — Public URL to the card image
  - `image_base64` string, nullable — Base64-encoded image data (data-URI prefix optional)
  - `k` integer — Ximilar recall breadth — number of similar cards to retrieve

## Response `200`

Successful match with the disambiguated best card and the candidates considered

- ImageMatchResponse — Response model for the image-match endpoint.
  - `success` boolean, required — Whether the search ran without error
  - `best_match` ImageMatchResult — The disambiguated best-match card, with the vision LLM's verdict.
    - `card_id` string, required — Unique card identifier
    - `description` string, nullable — Full card description
    - `player` string, nullable — Player or character name
    - `set` string, nullable — Card set name
    - `number` string, nullable — Card number in set
    - `variant` string, nullable — Card variant
    - `image` string, nullable — Card image URL
    - `category` string, nullable — Card category
    - `similarity` string, required — Ximilar visual similarity percentage (e.g. '95.23')
    - `confidence` number, required — LLM confidence in the variant match (0.0-1.0)
    - `reasoning` string, required — Short LLM explanation of the choice
  - `candidates` ImageMatchCandidate[] — Candidates the LLM considered — caller fallback when best_match is null
    - `card_id` string, required — Unique card identifier
    - `description` string, nullable — Full card description
    - `player` string, nullable — Player or character name
    - `set` string, nullable — Card set name
    - `number` string, nullable — Card number in set
    - `variant` string, nullable — Card variant
    - `image` string, nullable — Card image URL
    - `category` string, nullable — Card category
    - `similarity` string, required — Ximilar visual similarity percentage (e.g. '95.23')
  - `query_id` string, required — Ximilar query record ID
  - `message` string, nullable — Human-readable status

## Other responses

- `400` — Bad request — missing image input or invalid base64 data
- `413` — Image too large (max 10MB)
- `422` — Validation Error
- `502` — External API error — Ximilar visual recall or vision-LLM disambiguation failed
- `503` — Image search or variant disambiguation service is not configured on the server

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) · [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardhedger/card-hedge-api/revisions/f2d0e595be79/schema)