Integrating a Person ReID API: crops, embeddings and vector search

Your server sends an embedding request. The image is valid, but the connection times out before the response arrives. Did inference finish? Should you retry? Could a second request be charged twice? A safe Person ReID API integration begins with questions like these, not with the happy-path curl.

The PolyReID v1 endpoint takes one image crop containing one person and returns a versioned, L2-normalized appearance embedding. It is a similarity-retrieval component: person detection, video tracking, face recognition, names and identity decisions remain outside the endpoint boundary.

The public API overview and pricing is the source of truth for availability, limits and billing. Unless stated otherwise, the details below restate the published v1 contract as of this article’s update date; check that live page before implementation. This guide follows one request from input validation through retry, storage, retrieval and review.

If you are still deciding between maintaining a model stack and integrating a hosted endpoint, start with the Person ReID build-versus-buy framework.

Before the first request, fix the boundary

For v1, you 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.

Make the timeout safe to replay

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 uses a unique Idempotency-Key, with an encrypted 24-hour response cache. Replaying the same request and key returns the cached result, while 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]"

Return to the opening timeout: treat it as an unknown outcome. Retry the same payload with the same idempotency key rather than generating a new key. Your application should persist that key before sending the first attempt.

Retention choices

With retention=none, the source image is processed in request memory without intentional persistence; the encrypted 24-hour idempotency cache still applies. With retention=30d, the encrypted vector and technical metadata are additionally stored for 30 days, not the source image in 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.

Carry compatibility into the index

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.

Let errors decide the next action

Stable error responses contain a machine-readable code and request_id. Cases include 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).

Under the published charging rules, invalid images, provider errors and timeouts are uncharged; capture occurs 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.