---
name: polyreid-embeddings
description: Use PolyReID CLIP 2 (SigLIP2) to create image and text embeddings, compare images with prompts, and run semantic nearest-neighbour search.
---

# PolyReID Embeddings API

Use this skill when a task requires semantic image search, image–text matching, vehicle-view analysis, automatic labelling, or a first-pass anomaly review.

The service exposes CLIP 2 through a commercial API backed by SigLIP2. Images and text are mapped into the same normalized 768-dimensional embedding space. The API returns the vector, the model revision, the preprocessing version, and an ID. Use the ID for later searches when the embedding was created with `retention=30d`.

## Authentication and setup

1. Sign in at `https://polyreid.com/api`.
2. In the Developer Console, click **Generate**.
3. Review and accept the current developer terms in the confirmation modal.
4. Copy the returned secret immediately. It is shown only once.
5. Store it in a server-side environment variable such as `POLYREID_API_KEY`.

The account starts with a $10 evaluation balance. Never expose the Bearer key in browser code, client-side logs, prompts sent to third parties, or a source repository.

```bash
export POLYREID_API_KEY="preid_live_..."
export POLYREID_BASE_URL="https://polyreid.com"
```

## Non-negotiable request rules

- Send `Authorization: Bearer $POLYREID_API_KEY` on every API request.
- Generate a fresh `Idempotency-Key` for every new embedding request.
- Use `retention=30d` when the result must be searched later by ID. Use `retention=none` when no retained search is needed.
- Keep `model_revision` and `preprocess_version` next to every stored ID or vector.
- Compare vectors only when model, revision, and preprocessing version match.
- Treat similarity as ranking evidence, not as a calibrated probability, identity proof, or legal decision.
- Preserve a human review path for ambiguous, low-quality, or consequential cases.

## Core endpoints

### 1. Encode an image

The image endpoint accepts one JPEG, PNG, or WebP file in the multipart field `image`.

```bash
curl "$POLYREID_BASE_URL/api/v1/embeddings/clip2" \
  -H "Authorization: Bearer $POLYREID_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "image=@car-front.jpg" \
  -F "model=polyreid-clip2" \
  -F "retention=30d"
```

The response contains an `id`, `embedding`, `dimensions: 768`, `normalized: true`, `model_revision`, `preprocess_version`, `expires_at`, and `charged_usd`.

### 2. Encode text

Use natural-language descriptions, view labels, or search prompts. The text embedding is comparable with image embeddings.

```bash
curl "$POLYREID_BASE_URL/api/v1/embeddings/text" \
  -H "Authorization: Bearer $POLYREID_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "polyreid-clip2",
    "text": "front view of a dark red sports car",
    "retention": "30d"
  }'
```

### 3. Search by embedding ID

After an image or text embedding has been retained, send only its ID to search the account’s retained vectors.

```bash
curl "$POLYREID_BASE_URL/api/v1/search" \
  -H "Authorization: Bearer $POLYREID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embedding_id": "cm_embedding_id",
    "top_k": 10
  }'
```

The response contains ranked neighbors and a proximity score. The search is account-scoped and excludes the query vector itself.

## Main workflow: five-view vehicle dossier

When checking whether a client dossier contains consistent views of one vehicle:

1. Encode the five supplied images with `retention=30d`.
2. Store each returned ID with the dossier ID, expected view label, model revision, preprocessing version, source URI, and expiry.
3. Encode prompts such as `front view`, `back view`, `left side`, `right side`, or `interior view` when automatic view labelling is useful.
4. Search an incoming image ID against the retained dossier embeddings.
5. Compare the best score, the margin to the second candidate, view completeness, image quality, and consistency across all views.
6. Route the dossier to one of three review states:
   - **solid**: multiple views agree and the margin is strong;
   - **review**: the candidate is plausible but the margin is weak, a view is missing, or quality is poor;
   - **rework**: the image is invalid, too ambiguous, or inconsistent with the dossier.

Do not call the score a probability unless the application has calibrated it on a representative validation set. A nearest neighbor is simply the closest available candidate; it can still be wrong when the correct vehicle is absent.

## Automatic labelling and anomaly review

Use CLIP 2 for a flexible first pass:

- suggest front/back/side/interior labels;
- find images matching a text description;
- group visually and semantically related images;
- flag images that are far from the rest of a dossier;
- select candidates for human review.

After that pass, add specialist models where needed: vehicle detector, OCR, damage classifier, image-quality model, fine-grained make/model classifier, or metadata consistency rules. Let each model answer a narrow question. Combine their evidence instead of turning one embedding score into an automatic identity decision.

## Failure handling

- `401`: check the Bearer key and never retry with a key embedded in client code.
- `402`: the available balance is insufficient; failed requests are not charged.
- `413` or `415`: validate file size, pixels, and JPEG/PNG/WebP format before retrying.
- `409`: reuse the original response only when the same idempotency key and payload are intended; otherwise generate a new key.
- `429`: back off using response rate-limit headers.
- `503` or `504`: retry safely with the same idempotency key when the request may have reached inference.

For the complete contract, current limits, retention policy, and pricing, use `https://polyreid.com/api` and `https://polyreid.com/api/v1/openapi.json` as the source of truth.