Person Re-Identification API: integration guide

PolyReID turns one image crop containing one person into a versioned, L2-normalized appearance embedding. The API is designed for similarity retrieval and human review: it does not detect people, track them through video, recognise faces, assign names, or prove identity.

The public API overview and pricing is the source of truth for availability, limits and billing. This guide explains how to build a safe integration around the v1 contract.

The v1 contract

Send a JPEG, PNG or WebP of at most 10 MB and 25 megapixels. The image must contain a single person crop. A successful response includes:

• model alias polyreid-person-reid-v1;
• immutable model and preprocessing revisions;
• 768 finite float32 values, normalized to an L2 norm close to 1;
• retention and expiry metadata;
• the exact decimal amount charged and remaining API balance.

One raw vector occupies 3,072 bytes before database and metadata overhead. Compare vectors only when both the model revision and preprocessing version match.

Authentication and idempotency

Create an account with the developer signup flow, accept the current API Terms, top up the API wallet, and create a named key from the authenticated section of /api. A key secret is shown once. Store it in a server-side secret manager and never expose it in browser code or logs.

Every embedding request requires a unique Idempotency-Key. PolyReID keeps an encrypted response cache for 24 hours so a safe retry returns the same result and is charged only once. Reusing a key with a different payload returns 409.

curl https://polyreid.com/api/v1/embeddings \
  -H "Authorization: Bearer preid_live_REPLACE_ME" \
  -H "Idempotency-Key: 8e6cb2ce-25ee-4bc9-9475-68b12bd3fbcd" \
  -F "model=polyreid-person-reid-v1" \
  -F "retention=none" \
  -F "[email protected]"

Treat client timeouts as an unknown outcome. Retry the same request with the same idempotency key rather than generating a new key.

Retention choices

With retention=none, the source image is processed in request memory and is not intentionally persisted. The encrypted 24-hour idempotency cache still applies. With retention=30d, PolyReID additionally stores the encrypted vector and technical metadata for 30 days. The source image is never part of that retained object.

A retained vector can be fetched or deleted early through its embedding ID. Expired objects are inaccessible immediately, even when physical deletion is waiting for the next purge cycle.

Store and search vectors

Persist the embedding together with model, model_revision, preprocess_version, your own object identifier, and the legal retention information required by your workflow. For normalized vectors, cosine similarity and inner product produce the same ranking.

A simple retrieval flow is:

1. generate an embedding for every authorised gallery crop;
2. index those vectors in a project-scoped collection;
3. embed an authorised query crop with the exact same model revision;
4. return nearest neighbours as review candidates;
5. apply a domain-tested threshold and human confirmation.

Do not copy a threshold from another dataset. Camera placement, clothing, lighting, occlusion and population composition all affect the error distribution. Read how ReID embeddings work with vector databases before selecting an index and threshold.

Errors and charging

Stable error responses include a machine-readable code and request_id. Typical cases are invalid credentials (401), insufficient balance (402), idempotency conflict (409), payload limits (413), unsupported media (415), invalid image content (422), throttling (429), temporary capacity (503) and inference timeout (504).

Invalid images, provider errors and timeouts are not charged. A request is captured only after a valid embedding has been produced and, for 30-day retention, stored successfully.

Responsible deployment

Person-appearance embeddings can remain personal or biometric data depending on purpose and use. The customer is responsible for rights, notices, legal basis, access controls, data-subject procedures and any required impact assessment. Outputs must remain review candidates, never standalone evidence of identity or the sole basis for a consequential decision.

Review the public AI transparency and model-card status, the comparison with face recognition and tracking, and the current API Terms before production use.