Choisir une API de détection d’IA : dix points à vérifier avant l’intégration

Pour choisir une API de détection d’IA, vérifiez dix points qui décident de sa tenue en production : ce qu’elle contrôle et renvoie, ses limites d’entrée, le mode de livraison des résultats, la signature des webhooks, la sûreté des nouvelles tentatives, le comportement des erreurs et des limites de débit, ce qu’elle conserve et pendant combien de temps, la possibilité d’auditer un résultat et de le rattacher à une version de modèle, et ce que coûte une vérification échouée ou un essai. La plupart de ces points se tranchent dans la documentation du fournisseur, avant d’écrire la moindre ligne de code ; les autres exigent un court pilote.

Ce guide s’adresse aux développeurs et aux acheteurs techniques qui branchent un service de détection sur un processus de réception de dossiers, de sinistres, d’entrée en relation ou de modération. Il évalue l’interface, pas le détecteur. Pour la fiabilité, les faux positifs et la charge de la file d’examen, voyez le guide d’achat d’un logiciel de détection d’images IA et le guide sur la fiabilité. Un détecteur performant sur vos fichiers peut échouer en production si l’API qui l’entoure est difficile à rejouer, à auditer ou à payer.

Chaque point ci-dessous explique pourquoi il compte, comment le vérifier dans la documentation de n’importe quel fournisseur et ce que documente l’API Fileverity. Les mêmes dix questions valent pour tous les candidats, et ce guide ne cite ni ne classe aucun fournisseur.

Les dix points en un coup d’œil

La figure montre où chaque point se tranche. La documentation dit ce que le fournisseur promet, une clé de test montre la forme des requêtes et des réponses, et seul un pilote sur vos propres fichiers révèle les délais, la suppression et la facturation.

Périmètre et entrées

Modalité et sortie

Pourquoi c’est important. « Détection d’IA » recouvre des tâches distinctes : savoir si une image a été générée ou retouchée, si un document a été altéré ou contient des passages rédigés par IA, si un texte brut est rédigé par IA. Un fournisseur qui en couvre une n’en couvre pas forcément une autre. Une réponse réduite à un chiffre, sans périmètre ni preuve, est difficile à exploiter et à défendre. Vos analystes doivent savoir sur quoi porte un constat, et votre code de routage a besoin d’un champ stable lisible par une machine.

Comment le vérifier. Listez les tâches dont vous avez besoin et retrouvez chacune par son nom dans la documentation. Ouvrez le schéma de réponse et cherchez quatre éléments : une synthèse lisible par une machine (verdict, niveau ou action recommandée) distincte des constats détaillés ; des preuves qu’une personne peut lire ; un état « non évaluable » différent de « négatif » ; une version du schéma. Demandez des exemples de réponse pour un signalement, un résultat sans signalement, un résultat non concluant et un échec. La matrice de couverture du guide d’achat montre comment consigner les réponses.

Ce que documente Fileverity. Trois modèles, chacun listé avec ses limites et son instantané par GET /models : fvimg-2 pour les images, fvdoc-3 pour les documents et fvdoc-3-text pour le texte brut. Les vérifications d’image et de document renvoient un rapport complet, avec un niveau de synthèse et une action recommandée, les constats détaillés, un identifiant de rapport et un PDF scellé. Les vérifications de texte renvoient un résultat avec un verdict (rédigé par IA, mixte ou rédigé par un humain), des scores et les passages marqués. La documentation précise qu’un résultat de texte est une estimation statistique, pas une preuve de paternité, et qu’il ne doit pas décider seul d’une mesure qui touche une personne. Voir Vue d’ensemble, L’objet rapport et Détections de texte, ou les pages API de détection d’images IA et API de détection de fraude documentaire.

Limites d’entrée

Pourquoi c’est important. Les limites décident si votre flux réel passe : photos prises au téléphone, captures d’écran, scans, PDF de plusieurs pages, fichiers protégés par mot de passe, longs textes. Une limite découverte pour la première fois en production se traduit par des requêtes en échec et des utilisateurs mécontents.

Comment le vérifier. Relevez les limites de chaque modalité : formats acceptés, taille maximale, pixels ou pages, longueur du texte et langues. Vérifiez comment les gros fichiers sont envoyés (une requête ou un envoi par URL pré-signée), si le format est détecté d’après le contenu ou déduit du nom du fichier, et ce que renvoie chaque dépassement. Un code d’erreur distinct est bon signe ; une troncature silencieuse ou un 400 générique ne l’est pas. Soumettez ensuite les fichiers les plus gros, les plus petits et les plus ingrats que vous recevez vraiment, par exemple les pièces d’un dossier de sinistre ou d’une demande de crédit.

Ce que documente Fileverity. La page Fichiers liste les formats et les limites de chaque modèle, un envoi direct en multipart et un envoi par URL pré-signée pour les fichiers plus volumineux, la détection du format d’après le contenu et un code d’erreur par limite. Les documents chiffrés acceptent une option de mot de passe (Analyses). La longueur du texte et les langues figurent dans Détections de texte.

Résultats et livraison

Attente des résultats

Pourquoi c’est important. Un appel qui prend quelques secondes en laboratoire peut durer plus longtemps sous charge, et votre propre plateforme a ses délais d’expiration : fonctions serverless, passerelles, requêtes d’utilisateurs. Les fournisseurs répondent de deux façons. Un appel synchrone renvoie le résultat dans la réponse. Un appel asynchrone répond aussitôt avec un statut, et vous récupérez le résultat plus tard. Une intégration écrite pour le premier cas qui rencontre le second perd des résultats ou bloque des utilisateurs. La figure montre les trois façons dont un résultat asynchrone parvient à votre code.

Comment le vérifier. Cherchez le cycle de vie des statuts (processing, succeeded, failed, canceled) et, si le fournisseur peut garder la requête ouverte, la durée maximale d’attente documentée. Vérifiez comment et à quel rythme interroger, ce qui se passe quand la capacité est saturée, si les travaux en file indiquent leur position et si un travail peut être annulé sans frais. Un 503 accompagné d’un en-tête Retry-After, défini dans la RFC 9110, dit à votre code quoi faire. Pendant le pilote, mesurez le délai de bout en bout au volume attendu, pour votre type de fichier le plus lent. Un mode test qui répond instantanément n’apprend rien sur ce point.

Ce que documente Fileverity. Une vérification de texte est synchrone : le résultat est dans la réponse. Les vérifications d’image et de document sont asynchrones : la création renvoie 202 avec status: processing. Vous pouvez garder la requête ouverte avec un en-tête Prefer: wait, interroger GET /analyses/{id} ou vous abonner à un webhook, et il faut gérer le 202 même quand on attend, car les documents peuvent être mis en file. Quand la capacité est saturée, la création renvoie 503 service_unavailable avec retry-after et n’est pas facturée. Une vérification de document encore en cours peut être annulée sans frais. Voir Attendre, interroger ou utiliser des webhooks et Lorsque le service est saturé.

Signature des webhooks

Pourquoi c’est important. Un point de terminaison de webhook est une URL publique qui accepte des requêtes modifiant les données de vos dossiers. Sans vérification, quiconque la trouve peut envoyer un faux résultat « sans signalement ». La livraison est aussi fragile par nature : votre serveur redémarre, l’expéditeur doit donc réessayer, ce qui produit des doublons et des événements dans le désordre.

Comment le vérifier. Cherchez un schéma de signature documenté : un secret propre à chaque point de terminaison, une signature calculée sur le corps brut de la requête et un horodatage pour rejeter les requêtes trop anciennes. La spécification Standard Webhooks est une convention ouverte, avec les en-têtes webhook-id, webhook-timestamp et webhook-signature et une signature HMAC-SHA256 : des bibliothèques existantes savent la vérifier. Cherchez aussi comment les secrets sont renouvelés, le calendrier des nouvelles tentatives et leur arrêt, un identifiant d’événement stable pour dédoublonner, la présence du résultat ou d’un simple identifiant dans la charge utile, la façon dont les échecs vous sont signalés (journal des livraisons, renvoi, points de terminaison désactivés) et un événement de test à déclencher. Pendant le pilote, faites échouer une fois votre point de terminaison, puis envoyez un corps altéré et un horodatage périmé.

Ce que documente Fileverity. Les webhooks suivent Standard Webhooks, avec les trois en-têtes et une signature HMAC-SHA256 calculée sur l’identifiant de l’événement, l’horodatage et le corps brut. Le secret de signature est affiché une seule fois et peut être renouvelé ; la documentation fournit du code de vérification en JavaScript et en Python. La livraison est « au moins une fois », sans garantie d’ordre : dédoublonnez sur webhook-id. Les livraisons échouées sont retentées avec des délais croissants pendant plusieurs jours, un point de terminaison qui échoue en continu est désactivé et les propriétaires de l’espace de travail reçoivent un courriel ; la Console liste les livraisons récentes et permet d’en renvoyer une. Send test livre un événement d’exemple signé. L’événement ne contient pas le résultat : récupérez-le avec GET /analyses/{id}. Les vérifications de texte sont synchrones et n’envoient pas de webhook, et les clés de test n’en envoient jamais. Voir Vérifier la signature et Envoi et nouvelles tentatives.

Fiabilité sous nouvelles tentatives et sous charge

Idempotence et nouvelles tentatives

Pourquoi c’est important. Le réseau peut défaillir entre votre requête et la réponse. Si une nouvelle tentative peut créer une seconde vérification, vous payez deux fois et vous ouvrez peut-être un dossier en double. Si vous ne réessayez jamais, vous perdez du travail. Une clé d’idempotence permet au fournisseur de reconnaître une nouvelle tentative et de renvoyer le premier résultat.

Comment le vérifier. Cherchez un en-tête de clé d’idempotence sur chaque point d’accès qui crée quelque chose ou qui coûte de l’argent. Lisez ce qui se passe quand la même clé est rejouée (même réponse, signalée comme rejouée), quand elle est réutilisée avec un autre corps (elle doit être refusée, pas acceptée en silence), pendant que la première requête s’exécute encore et après une erreur, ainsi que la durée de conservation des clés et leur périmètre. L’en-tête est décrit par un brouillon de l’IETF qui n’était pas encore une RFC en novembre 2026 : les fournisseurs diffèrent dans le détail, testez donc. Pendant le pilote, envoyez deux fois la même requête, coupez la connexion en cours de requête, puis confirmez un seul résultat et une seule facturation.

Ce que documente Fileverity. Un en-tête Idempotency-Key fonctionne sur chaque point d’accès POST : vérifications de texte, envois de fichiers, création et annulation de vérification. Un rejeu renvoie la réponse enregistrée avec idempotent-replayed: true, sans rien relancer ni refacturer. La même clé avec un autre corps renvoie 409 idempotency_mismatch, et la même clé pendant que la première requête s’exécute renvoie 409 idempotency_in_progress. Les réponses d’erreur ne sont pas enregistrées : une nouvelle tentative après une erreur relance la requête. Les clés sont propres à l’espace de travail, au mode (live ou test) et au point d’accès, et conservées pendant une durée documentée. Voir Idempotence.

Erreurs et identifiants de requête

Pourquoi c’est important. Votre code doit décider quoi réessayer, quoi corriger, quoi montrer à un utilisateur et quoi transmettre au support du fournisseur. Les messages d’erreur rédigés en prose évoluent, et le code qui les analyse casse. Un identifiant de requête permet aux deux parties de retrouver la même requête plus tard.

Comment le vérifier. Cherchez des erreurs dans un format JSON cohérent, avec un code stable lisible par une machine distinct du message destiné aux humains, un tableau de tous les codes avec leur statut HTTP et la conduite à tenir (réessayer ou non), et un identifiant de requête dans un en-tête de chaque réponse, succès compris. Vérifiez que la documentation indique si une vérification échouée est facturée. Pendant le pilote, provoquez chaque famille de pannes (clé invalide, fichier trop volumineux, format non pris en charge, identifiant inconnu, solde vide) et confirmez que le code seul suffit à les distinguer.

Ce que documente Fileverity. Les erreurs portent type, code, message, param et request_id, et la documentation recommande de se fonder sur code plutôt que sur le message. Chaque réponse a un en-tête x-request-id, et le tableau des codes d’erreur est généré à partir des définitions de l’API elle-même. La documentation indique quelles erreurs réessayer et lesquelles corriger d’abord, et une vérification qui se termine par une erreur n’est pas facturée. Indiquez l’identifiant de requête quand vous écrivez à hello@fileverity.com ou via la page de contact. Voir Erreurs.

Limites de débit

Pourquoi c’est important. Une rafale, comme l’import d’un arriéré ou un traitement de fin de mois, peut atteindre les limites. Mal gérée, elle produit des échecs et des nouvelles tentatives qui aggravent la situation. Les limites disent aussi comment le fournisseur attend qu’on l’utilise : étaler la charge et préférer les webhooks à une interrogation serrée.

Comment le vérifier. Cherchez la limite par clé ou par compte et sa fenêtre, des en-têtes de réponse qui indiquent la limite, ce qu’il reste et le moment de la réinitialisation, et une réponse 429 accompagnée d’un en-tête Retry-After (la RFC 6585 définit le statut 429). Cherchez d’autres plafonds, comme les envois simultanés ou en attente, et la façon de demander des limites plus élevées. Si le mode test du fournisseur applique les mêmes limites, lancez-y d’abord une rafale.

Ce que documente Fileverity. Chaque clé d’API a une limite par minute qui couvre tous les points d’accès, y compris les requêtes qui renvoient une erreur. Toute réponse authentifiée porte x-ratelimit-limit-requests, x-ratelimit-remaining-requests et x-ratelimit-reset-requests, et 429 rate_limited porte retry-after. Un plafond distinct sur les fichiers envoyés non expirés renvoie pending_files_limit, sans retry-after. Les clés de test et les clés live partagent les limites de débit : vous pouvez donc répéter votre stratégie de repli avec une clé de test. Des limites plus élevées s’obtiennent auprès de l’équipe commerciale. Voir Limites de débit et en-têtes.

Données, preuves et coût

Conservation des données

Pourquoi c’est important. Les fichiers soumis à vérification sont souvent personnels ou sensibles : photos de sinistre, bulletins de paie, contrats. Le fournisseur devient un sous-traitant de ces données. Vous devez savoir ce qui est conservé, où, combien de temps, qui y a accès et si les données servent à entraîner des modèles.

Comment le vérifier. Demandez une réponse par catégorie de données : fichiers envoyés, texte soumis, données dérivées, résultats, journaux et sauvegardes. « Nous supprimons les fichiers » ne répond pas tant que l’on ne sait pas ce qui est supprimé, quand, et ce qui subsiste. Cherchez un tableau de conservation dans la documentation, un point d’accès de suppression anticipée, les lieux de traitement et les sous-traitants ultérieurs, une déclaration sur l’usage pour l’entraînement, un accord de traitement des données et une option de déploiement privé. Quand les fichiers contiennent des données personnelles, l’article 28 du RGPD impose un contrat avec le sous-traitant (RGPD, article 28, sur le site de la CNIL), et les transferts hors de l’Union exigent un fondement juridique (chapitre V du RGPD) ; la liste des décisions d’adéquation de la Commission européenne indique les pays reconnus, et chaque lieu de traitement se vérifie séparément. La qualification juridique revient à votre DPO. Pendant le pilote, confirmez qu’un fichier a disparu après sa vérification et que les résultats conservés expirent comme annoncé.

Ce que documente Fileverity. Un tableau de conservation, dans Conservation des données et sécurité, couvre chaque catégorie de données. Les fichiers envoyés sont supprimés dès qu’une vérification démarre et, en tout état de cause, au terme d’une durée indiquée ; DELETE /files/{id} en supprime un plus tôt. Le texte soumis est évalué puis écarté, jamais stocké. Les résultats des vérifications sont conservés pendant une durée limitée, ceux des textes sans le texte. Les pièces probantes d’un document (images de pages, extraits) sont conservées moins longtemps que le résultat : téléchargez le rapport PDF dès la fin de la vérification si vous voulez qu’il les contienne. Les journaux de requêtes n’enregistrent ni le corps des requêtes ni celui des réponses. Les lieux de traitement et les sous-traitants ultérieurs figurent sur la page Sécurité, les conditions dans l’accord de traitement des données, et le déploiement privé est proposé sur demande aux clients Entreprise.

Preuves d’audit et versions du modèle

Pourquoi c’est important. Quand un dossier signalé est contesté des mois plus tard, vous devez montrer ce qui a été contrôlé, quand, avec quelle version de quel modèle, et que le fichier n’a pas changé depuis. Un simple score dans votre base ne le permet pas. Si un fournisseur modifie son modèle sans vous prévenir, les résultats sur un même fichier peuvent changer : vous ne pouvez plus comparer un résultat de pilote à la production, ni expliquer l’écart entre deux vérifications.

Comment le vérifier. Cherchez un identifiant stable pour chaque résultat, que vous conservez avec le dossier, l’empreinte (hachage) du fichier examiné, un horodatage de confiance émis par une autorité d’horodatage (RFC 3161) pour que l’heure ne repose pas sur la seule horloge du fournisseur, un rapport téléchargeable et un moyen, pour un tiers, de le confirmer sans compte. Vérifiez que chaque résultat nomme la version exacte du modèle, si vous pouvez figer une requête sur une version et pendant combien de temps elle reste disponible, et comment les changements et les retraits sont annoncés. Le guide sur l’horodatage certifié et l’empreinte SHA-256 explique ce que prouvent séparément une empreinte et un horodatage.

Ce que documente Fileverity. Les rapports d’image et de document portent un identifiant de rapport, l’empreinte SHA-256 du fichier examiné, un horodatage RFC 3161 et une page de vérification publique que toute personne disposant du lien peut consulter sans compte, avec un PDF scellé. Chaque résultat nomme l’instantané qui l’a produit, un identifiant de modèle comme fvimg-2 désigne un instantané daté, et passer l’identifiant d’un instantané comme model y fige la requête. Les changements de la v1 sont additifs et consignés dans le journal des modifications : les clients doivent donc ignorer les champs qu’ils ne connaissent pas. Les résultats de texte portent un identifiant de détection et l’instantané qui les a produits. Les délais de préavis avant le retrait d’un instantané relèvent de votre contrat : demandez-les par écrit. Voir L’objet rapport, Conventions et le Journal des modifications.

Facturation et mode test

Pourquoi c’est important. Une grille tarifaire cache les règles qui font la facture : l’unité facturable, le sort des vérifications échouées, annulées ou rejouées, les arrondis et ce que peut coûter un traitement qui s’emballe. Il faut aussi pouvoir construire et tester l’intégration sans dépenser d’argent ni polluer les données de production.

Comment le vérifier. Relevez l’unité de facturation de chaque modalité (par image, par document, par tranche de caractères) et la règle d’arrondi. Vérifiez si les requêtes échouées, annulées ou rejetées sont facturées, si le modèle est prépayé ou par abonnement, et s’il existe des plafonds de dépenses, des alertes de solde bas et un relevé d’usage que vous pouvez rapprocher de vos propres comptes. Un bon mode test ne facture jamais, applique la même validation et dit précisément ce qu’il simule et ce qu’il ne simule pas : les délais, les webhooks et les vrais résultats sont les lacunes habituelles. Pendant le pilote, rapprochez le relevé d’usage du fournisseur de votre propre journal, en y incluant un échec volontaire.

Ce que documente Fileverity. L’API est prépayée depuis le solde de l’espace de travail, sans abonnement. Les prix s’appliquent par vérification d’image, par vérification de document et par tranche de caractères de texte, arrondie à l’unité supérieure par requête. Pour les vérifications d’image et de document, le prix est réservé à la création et libéré en cas d’échec ou d’annulation, et les requêtes rejetées avant évaluation ne sont pas facturées. Le démarrage gratuit est consommé avant le solde. Chaque clé peut avoir un plafond de dépenses mensuel, une alerte de solde bas envoie un courriel et un webhook balance.low, et chaque vérification indique son coût dans usage. Les clés de test ne facturent jamais et n’utilisent pas le démarrage gratuit, renvoient aussitôt un échantillon fixe, appliquent la même validation, les mêmes limites de débit et les mêmes codes d’erreur, et n’envoient aucun webhook hormis l’événement de test de la Console. Les identifiants de rapport d’exemple commencent par FV-TEST- et n’ont pas de page de vérification publique. Les prix en vigueur figurent dans Tarifs et facturation et sur la page API ; le comportement des clés de test est décrit dans Authentification et clés.

Questions fréquentes

Faut-il choisir une API synchrone ou asynchrone ?

Aucune n’est meilleure en soi. Les entrées courtes, comme un texte brut, conviennent à un appel synchrone ; les fichiers qui demandent une analyse plus lourde renvoient en général d’abord un statut. L’essentiel est que la documentation définisse le cycle de vie, prenne en charge l’attente, l’interrogation et les webhooks, et que votre code gère un statut en attente.

Faut-il des webhooks, ou l’interrogation suffit-elle ?

L’interrogation suffit pour un prototype ou un faible volume. Les webhooks économisent des requêtes et du quota de débit, et conviennent à la production. Dans les deux cas, vérifiez la signature et gérez les doublons ainsi que l’état en attente.

Une clé d’idempotence est-elle normalisée ?

C’est une convention répandue, qu’un brouillon de l’IETF décrit sans qu’il soit devenu une RFC en novembre 2026. Considérez le comportement exact comme propre à chaque fournisseur et testez-le. Celui de Fileverity est décrit dans la page Idempotence.

Une bonne API garantit-elle un détecteur fiable ?

Non. Ces points portent sur l’intégration, pas sur la qualité de la détection. Évaluez la détection sur vos propres fichiers, avec des étiquettes auxquelles vous croyez, en vous appuyant sur le guide sur la fiabilité et le guide d’achat.

Puis-je essayer l’API Fileverity sans payer ?

Oui. Votre premier espace de travail inclut un démarrage gratuit, et les clés de test ne facturent jamais. Suivez le Démarrage rapide et consultez Tarifs et facturation pour les conditions.

Une liste de contrôle pour le pilote

Menez le pilote en trois passes et conservez une trace datée de chaque réponse. D’abord une passe documentaire : répondez aux dix points à partir de la documentation de chaque candidat et écartez d’emblée les candidats manifestement inadaptés avant d’écrire du code. Ensuite une passe avec clé de test : construisez l’intégration sur le mode test. Enfin une passe en conditions réelles : utilisez une clé live avec un plafond de dépenses bas et un échantillon de fichiers que vous avez le droit d’envoyer. Pour l’échantillonnage, les étiquettes et la notation de la qualité de détection elle-même, suivez la conception du pilote décrite dans Choisir un logiciel de détection d’images IA.

Gardez les réponses à côté de la matrice de couverture et de la grille de notation du guide d’achat. Pour démarrer avec Fileverity, lisez la page API, les pages de détection d’images et de fraude documentaire et le Démarrage rapide.

Par Yang Zheng · Relu par Bill Liu