API de ré-identification de personnes : guide d’intégration

PolyReID transforme une image recadrée contenant une personne en embedding d’apparence normalisé et versionné. L’API sert à proposer des résultats similaires à un opérateur humain : elle ne détecte pas les personnes, ne suit pas une vidéo, ne reconnaît pas un visage, n’attribue pas de nom et ne prouve pas une identité.

La page API et tarifs reste la source de vérité pour la disponibilité, les limites et la facturation. Ce guide décrit une intégration v1 maîtrisée.

Le contrat v1

Envoyez un fichier JPEG, PNG ou WebP de 10 Mo et 25 mégapixels au maximum. L’image doit être le crop d’une seule personne. Une réponse réussie contient :

• l’alias polyreid-person-reid-v1 ;
• les révisions immuables du modèle et du prétraitement ;
• 768 valeurs float32 finies, normalisées avec une norme L2 proche de 1 ;
• les informations de rétention et d’expiration ;
• le montant décimal facturé et le solde API restant.

Un vecteur brut occupe 3 072 octets, hors métadonnées et surcoût de la base. Ne comparez que des vecteurs ayant la même révision de modèle et la même version de prétraitement.

Authentification et idempotence

Créez un compte via le parcours développeur, acceptez les API Terms en vigueur, créditez le wallet API, puis créez une clé nommée depuis la zone connectée de /api. Le secret n’est affiché qu’une fois. Conservez-le dans un gestionnaire de secrets côté serveur, jamais dans le navigateur ou les logs.

Chaque requête exige un Idempotency-Key unique. PolyReID conserve pendant 24 heures un cache de réponse chiffré : un retry identique renvoie le même résultat sans double facturation. Réutiliser la clé avec un autre contenu produit une erreur 409.

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

Après un timeout côté client, réessayez avec la même clé d’idempotence : l’issue de la première tentative peut être inconnue.

Choix de rétention

Avec retention=none, l’image source est traitée en mémoire et n’est pas intentionnellement persistée. Le cache d’idempotence chiffré de 24 heures reste actif. Avec retention=30d, PolyReID conserve en plus le vecteur chiffré et ses métadonnées techniques pendant 30 jours. L’image source ne fait jamais partie de cet objet.

Un vecteur retenu peut être récupéré ou supprimé avant terme. À expiration, son accès est immédiatement refusé, même si la suppression physique attend le prochain cycle de purge.

Indexation et recherche

Conservez l’embedding avec model, model_revision, preprocess_version, votre identifiant métier et les informations de rétention utiles. Pour des vecteurs normalisés, la similarité cosinus et le produit scalaire donnent le même classement.

Le flux recommandé est le suivant :

1. générer les embeddings des crops autorisés ;
2. les indexer dans une collection isolée par projet ;
3. calculer le vecteur d’une requête autorisée avec la même révision ;
4. retourner les voisins les plus proches comme candidats ;
5. appliquer un seuil validé sur votre domaine et une confirmation humaine.

Un seuil choisi sur un autre jeu de données n’est pas réutilisable tel quel. Les caméras, les vêtements, la lumière, les occlusions et la population modifient la distribution des erreurs.

Erreurs et facturation

Les erreurs stables incluent un code lisible par machine et un request_id : authentification (401), solde insuffisant (402), conflit d’idempotence (409), taille (413), média non supporté (415), image invalide (422), limitation (429), capacité temporaire (503) et timeout d’inférence (504).

Les images invalides, erreurs fournisseur et timeouts ne sont pas facturés. La dépense n’est capturée qu’après production d’un vecteur valide et, pour la rétention 30 jours, après sa persistance.

Déploiement responsable

Un embedding d’apparence peut rester une donnée personnelle ou biométrique selon sa finalité. Le client doit gérer les droits, l’information, la base légale, les contrôles d’accès, les droits des personnes et les analyses d’impact nécessaires. Le résultat doit rester un candidat à examiner, jamais une preuve autonome d’identité ni le fondement unique d’une décision ayant des conséquences.

Consultez le statut de transparence et la fiche modèle ainsi que les API Terms en vigueur avant tout usage en production.