CAcardhedger
Image Search

Search Cards by Image

Changed on

Upload an image or provide an image URL to find visually similar cards. Returns a ranked list of candidates with CardHedge catalog data where available (including each card's prices section: grade/price pairs, one per grade) and AI fallback identification otherwise.

Need a single best answer with the correct variant? Use POST /v1/cards/image-match — an AI-powered upgrade that identifies one specific card and resolves its parallel/variant (e.g. Base vs. Silver vs. Red) instead of returning a ranked list.

post/v1/cards/image-search

Request

  • Base URL
    https://api.cardhedger.com
  • Auth
    API key in header X-API-Key

Request body

image_urlstring nullable

Public URL to card image

image_base64string nullable

Base64-encoded image data (with or without data URI prefix)

kinteger

Number of similar results to return (max: 50)

Example request

{
  "image_url": "https://example.com/card.jpg",
  "k": 10
}

Response

Successful search with results

successboolean required

Whether the search was successful

total_resultsinteger required

Total number of results returned

query_idstring required

Ximilar query record ID for tracking

has_cardhedge_matchesboolean required

Whether any results have CardHedge data

messagestring nullable

Additional information about the search

Example response

{
  "has_cardhedge_matches": true,
  "message": "Results include CardHedge data where available, AI identification as fallback",
  "query_id": "query_abc123",
  "results": [
    {
      "card_data": {
        "card_id": "1587446850514x224832321163624450",
        "category": "Baseball",
        "description": "Ken Griffey Jr. 1989 Upper Deck Baseball",
        "image": "https://example.com/card.jpg",
        "number": "1",
        "player": "Ken Griffey Jr.",
        "set": "1989 Upper Deck Baseball",
        "variant": "Rookie Card"
      },
      "distance": 0.0477,
      "product_id": "1587446850514x224832321163624450",
      "similarity": "95.23",
      "ximilar_id": "xim_abc123"
    }
  ],
  "success": true,
  "total_results": 5
}

Changes

  • 7bafee2d817bRevision changes
    • info

      added the optional property //// to the response with the status