---
title: "Vector image search"
method: POST
path: "/search/vector"
tags: ["search"]
---

# Vector image search

`POST /search/vector`

Find visually similar trading cards using a precomputed image embedding.

**Use this endpoint for:**
- image-based card recognition flows
- camera upload search
- similarity search from a cropped card artwork image

**Preparation requirements:**
- Generate a single image embedding from one card image at a time.
- Use CLIP ViT-B/32-compatible image preprocessing so the model input is prepared as float32 pixel values with shape `[1, 3, 224, 224]`.
- Use the model embedding output with shape `[1, 512]`.
- L2-normalize the 512-dimensional vector before sending it to this API.
- Send only the normalized numeric vector in `vectors`. Do not send raw pixels, base64 image data, or wrapped model response objects.

**Behavior:**
- Accepts exactly one 512-dimensional embedding per request.
- Accepts an optional `limit` between 1 and 10. If omitted, the API returns up to 5 matches.
- Returns visually similar card matches, ordered by similarity score.
- Each match includes the scored card identifier fields needed to resolve the card and display a primary image preview.

**Good to know:**
- This route is designed for image embeddings only. It does not generate embeddings from uploaded files.
- Invalid vectors are rejected before any similarity search is performed.

## Request body

- VectorSearchRequest — Request payload for similarity search using a precomputed trading card image embedding.
  - `limit` integer — Maximum number of matches to return. Must be between 1 and 10. Defaults to 5.
  - `vectors` number[], required — A 512-dimensional image embedding prepared from a single trading card image.

## Response `200`

Scored vector matches for the submitted image embedding

- VectorSearchResponse — Similarity search results for a single trading card image embedding.
  - `count` integer, required — Number of matches returned for the submitted vector.
  - `matches` VectorSearchMatch[], required — Scored vector matches sorted from most similar to least similar.
    - `urn` string, required
    - `game` 'Pokemon', required
    - `title` string, required
    - `number` string, nullable
    - `image` string, required
    - `score` number, required

## Other responses

- `400` — Validation error. The request must include a single non-zero 512-dimensional numeric vector.

---

[API](https://skmtc.net/managem/apis/managem-api.md) · [All operations](https://skmtc.net/managem/apis/managem-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/managem/managem-api/versions/6367b514f6ea/schema)