Documentation de l'API
ISO 27001SOC 2 CertifiedGDPR Compliant

API de détection de texte IA

Documentation complète pour intégrer l'API de détection IA de TruthScan dans vos applications.

Essayez sans code en visitant notre endpoint FastAPI : https://detect-text.truthscan.com/docs

Authentification

TruthScan utilise des clés API pour autoriser l'accès à l'API. Vous pouvez obtenir votre clé API en haut de la page dans notre portail développeur.

TruthScan attend que la clé API soit incluse dans toutes les requêtes API au serveur dans un corps de requête qui ressemble à ceci :

{
  "key": "YOUR API KEY GOES HERE"
}

Vous devez remplacer YOUR API KEY GOES HERE par votre clé API personnelle.

Pour les scénarios web socket, vous devrez envoyer votre Organization ID comme partie de l'url. Vous pouvez obtenir votre Organization ID en haut de la page dans notre portail développeur.

TruthScan attend que votre Organization ID soit inclus dans l'url de toutes les requêtes web socket. La documentation ressemblera à ceci :

wss://detect-text.truthscan.com/ws/$ORG_ID

Vous devez remplacer $ORG_ID par votre Organization ID personnelle.

Détecteur IA

Détecter

Cet endpoint vous permet de soumettre du texte pour détection IA. Au moins 200 mots sont recommandés pour une meilleure précision.

POST https://detect-text.truthscan.com/detect

Seuil

Cet endpoint renvoie un score "result" de 1-100. Pour une meilleure précision, tout score sous 50 est considéré définitivement humain. 50-60 est possible IA. Plus de 60 est définitif IA. C'est le résultat le plus précis, avec une précision de 99%+.

Les scores pour d'autres détecteurs, tels que Writer et Copyleaks, sont approximatifs et pas aussi précis que le score "result" principal.

Sauts de ligne

Si vous envoyez des données en JSON, les sauts de ligne doivent être encodés comme \n à l'intérieur de la chaîne.

Exemple de requête

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "retry_count": 0,
  "generate_analysis_details": true
}'

Ici, l'entrée de requête doit être inférieure à 30 000 mots.

Paramètres Optionnels

  • model: Modèle de détection IA à utiliser (par défaut : 'xlm_ud_detector')
  • retry_count: Nombre de tentatives en cas d'échec du traitement (par défaut : 0)
  • generate_analysis_details: Définir sur 'true' pour activer les résultats d'analyse approfondie IA (par défaut : 'false'). Lorsqu'activé, la réponse de requête inclura les champs analysis_results_status et analysis_results.

Exemple de réponse

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xlm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

La réponse contient l'ID assigné par le serveur du document. À ce stade, le document est maintenant en file d'attente pour traitement. Vous pouvez utiliser l'endpoint API /query pour interroger le statut de la requête de détection IA. Le temps moyen pour compléter une vérification de détection IA est entre 2-4 secondes. Cela peut prendre plus longtemps selon le nombre de mots.

Interroger

Cet endpoint accepte un id de document renvoyé par la requête /detect. Et renvoie le statut de la soumission du document ainsi que le résultat de l'opération de détection IA telle que gérée par divers détecteurs IA tiers.

POST https://detect-text.truthscan.com/query

Exemple de requête

curl -X 'POST' \
  'https://detect-text.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "DOCUMENT-ID-GOES-HERE"
}'

Exemple de réponse

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "scoreGptZero": 50.0,
        "scoreOpenAI": 0.0,
        "scoreWriter": 0.0,
        "scoreCrossPlag": 0.0,
        "scoreCopyLeaks": 50.0,
        "scoreSapling": 0.0,
        "scoreContentAtScale": 0.0,
        "scoreZeroGPT": 50.0,
        "human": 88.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "result_categories": {
        "advanced": 12,
        "standard": 12
    },
    "status": "done",
    "retry_count": 0
}

Interprétation des Résultats

  • result: Score de 0-100 indiquant la probabilité que le texte soit généré par IA. Moins de 50 = définitivement humain. 50-60 = possiblement IA. Plus de 60 = définitivement IA.
  • label: La détermination globale : 'Human', 'AI' ou 'Paraphrase'
  • result_details scores: Scores approximatifs des détecteurs tiers : GPTZero, OpenAI, Writer, CrossPlag, CopyLeaks, Sapling, ContentAtScale, ZeroGPT (chacun 0, 50 ou 100)
  • human: Moyenne de tous les scores des détecteurs tiers indiquant à quel point le texte semble humain
  • result_categories.advanced: Catégorie de résultat avancée avec notation échelonnée (format 1-99)
  • result_categories.standard: Catégorie de résultat standard
  • analysis_results_status: Statut de l'analyse approfondie IA ('pending', 'ready', 'skipped' ou null). Quand 'pending', continuez à interroger le point de terminaison /query — l'analyse est encore en cours en arrière-plan. Quand 'ready', le champ analysis_results contient l'analyse terminée. Quand 'skipped', null ou absent, l'analyse approfondie n'est pas disponible pour ce texte.
  • analysis_results: Résultats d'analyse approfondie IA (disponibles quand analysis_results_status est 'ready'). Contient : agreement (strong/moderate/weak/disagreement), confidence (0-100), keyIndicators (tableau d'indicateurs textuels trouvés), detailedReasoning (explication), linguisticPatterns (tableau de modèles linguistiques observés) et recommendations (éléments actionnables).

Ici, "result": 12.0 indique l'humanité de l'entrée. Cela signifie que étant donné qu'il est inférieur au seuil de 50%, le texte est définitivement humain. De même, les valeurs sous result_details indiquent l'humanité de l'entrée. Par exemple "scoreZeroGPT": 50.0 signifie que le texte est probablement 50% écrit par l'humain selon ZeroGPT. Il en va de même pour le reste des autres détecteurs.

Vérifier les crédits utilisateur

Cet endpoint accepte l'apikey de l'utilisateur via l'en-tête. Et renvoie les détails de crédit de l'utilisateur.

GET https://detect-text.truthscan.com/check-user-credits

Exemple de requête

curl -X 'GET' \
  'https://detect-text.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

Exemple de réponse

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Résultats d'Analyse (Analyse Approfondie Asynchrone)

Lorsque vous définissez 'generate_analysis_details' sur 'true' dans la requête /detect, TruthScan exécute une analyse approfondie IA en arrière-plan après la fin de la détection initiale. La réponse initiale retournera avec le statut 'done' et vos résultats de détection prêts à l'emploi, mais le champ analysis_results_status peut encore être 'pending'. Vous pouvez utiliser les résultats initiaux immédiatement et optionnellement interroger jusqu'à ce que l'analyse approfondie soit terminée.

1. Résultat Initial Établi (Analyse Encore en Attente)

Lorsque vous soumettez avec 'generate_analysis_details': true et interrogez pour la première fois avec le statut 'done', les résultats principaux de détection (result, label, result_details) sont prêts. Cependant, analysis_results_status peut être 'pending' — cela signifie que l'analyse approfondie IA est encore en cours en arrière-plan.

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

Que faire

Vous pouvez utiliser les résultats de détection initiaux (result, label, scores result_details) immédiatement. Si vous avez aussi besoin de l'analyse approfondie, continuez à interroger le point de terminaison /query avec le même ID de document jusqu'à ce que analysis_results_status change de 'pending'.

2. Continuer à Interroger pour les Résultats d'Analyse

Continuez à appeler le point de terminaison /query avec le même ID de document. Vérifiez le champ analysis_results_status à chaque réponse. Quand il passe de 'pending' à 'ready', l'objet analysis_results sera rempli.

curl -X 'POST' \
  'https://detect-text.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9"
}'

3. Analyse Terminée — Réponse Complète

Une fois que analysis_results_status est 'ready', l'objet analysis_results contient l'analyse approfondie IA complète avec le niveau d'accord, la confiance, les indicateurs clés, le raisonnement détaillé, les modèles linguistiques et les recommandations.

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "status": "done",
    "result": 73.2,
    "label": "AI",
    "result_details": {
        "scoreGptZero": 100.0,
        "scoreOpenAI": 50.0,
        "scoreWriter": 50.0,
        "scoreCrossPlag": 100.0,
        "scoreCopyLeaks": 100.0,
        "scoreSapling": 50.0,
        "scoreContentAtScale": 50.0,
        "scoreZeroGPT": 100.0,
        "human": 25.0,
        "analysis_results_status": "ready",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 78,
            "keyIndicators": [
                "Highly consistent sentence structure throughout",
                "Formulaic transitions between paragraphs",
                "Lack of personal voice or idiosyncratic expressions"
            ],
            "detailedReasoning": "The text exhibits hallmarks of AI-generated content including uniform sentence complexity, predictable paragraph transitions, and an absence of personal stylistic quirks. The vocabulary choices are sophisticated but lack the natural variation typical of human writing.",
            "linguisticPatterns": [
                "Uniform sentence length distribution",
                "Repetitive use of hedging language",
                "Absence of colloquialisms or informal markers"
            ],
            "recommendations": [
                "Cross-reference with the original source if available",
                "Check for consistent writing style across longer documents",
                "Compare with known writing samples from the claimed author",
                "Consider the context in which the text was produced"
            ]
        }
    },
    "result_categories": {
        "advanced": 73,
        "standard": 73
    }
}

Quand l'Analyse N'est Pas Disponible

Si analysis_results_status est 'skipped', null ou absent, aucune analyse approfondie ne sera produite pour ce texte. Cela se produit quand 'generate_analysis_details' n'a pas été défini sur 'true' dans la requête /detect, ou pour certains scénarios de traitement. Vous devez considérer les résultats de détection initiaux comme définitifs.

{
    "status": "done",
    "result": 12.0,
    "label": "Human",
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

Champs des Résultats d'Analyse

  • analysis_results_status: 'pending' = en cours de traitement, 'ready' = résultats disponibles, 'skipped' / null / absent = non disponible pour ce texte
  • analysis_results.agreement: Force de l'accord entre l'analyse approfondie et la détection initiale (strong / moderate / weak / disagreement)
  • analysis_results.confidence: Score de confiance de l'analyse approfondie (0-100)
  • analysis_results.keyIndicators: Tableau d'indicateurs textuels spécifiques trouvés dans le texte
  • analysis_results.detailedReasoning: Explication de 2 à 4 phrases expliquant pourquoi le texte a été classifié ainsi
  • analysis_results.linguisticPatterns: Tableau de modèles linguistiques observés (ex. : cohérence de structure des phrases, modèles de vocabulaire)
  • analysis_results.recommendations: Tableau de recommandations actionnables pour comprendre l'authenticité du texte

Détection IA niveau phrase

Le détecteur IA niveau phrase fonctionne sur un protocole basé sur WebSocket.

Voici les étapes nécessaires pour obtenir des résultats niveau phrase pour votre texte :

  • Se connecter au WebSocket
  • Écouter tous les événements reçus du WebSocket
  • Envoyer une requête document_watch
  • Recevoir un événement document_id
  • Prendre l'id généré par la réponse document_id et soumettre un document pour détection IA
  • Commencer à recevoir des événements document_chunk. Les événements document_chunk renverront chaque phrase avec le résultat niveau phrase
  • Lorsque le document termine le traitement, vous recevrez un événement document_done

Se connecter au WebSocket

Cet endpoint vous permet d'établir la connexion WebSocket

wss://detect-text.truthscan.com/ws/$ORG_ID

Exemple de code

ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");

Écouter tous les événements reçus du WebSocket

Une fois la connexion WebSocket établie, écoutez les événements envoyés via la connexion WebSocket.

Exemple de code

ws.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

Envoyer une requête document_watch

Envoyer l'intérêt d'envoyer un document en envoyant une requête document_watch sur le WebSocket

Exemple de code

ws.send(JSON.stringify({
    "event_type": "document_watch",
    "api_key": "$API_KEY",
}))

Recevoir un événement document_id

Après avoir envoyé un événement document_watch, le serveur renvoie un événement document_id.

Exemple de réponse

{
  "event_type": "document_id",
  "success": true,
  "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Soumettre une requête de détection IA

Prendre l'id généré par la réponse document_id et soumettre un document pour détection IA

POST https://detect-text.truthscan.com/detect

Exemple de requête

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

Recevoir résultats niveau phrase

Commencer à recevoir des événements document_chunk. Les événements document_chunk renverront chaque phrase avec le résultat niveau phrase

Exemples de réponses

{
    "event_type": "document_chunk",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector",
    "chunk": "Citizen science involves the public in scientific research.",
    "result": 0.714
}

Lorsque le document termine le traitement, vous recevrez un événement document_done.

Exemples de réponses

{
    "event_type": "document_done",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector"
}

Gérer circonstances exceptionnelles

Si pour une raison quelconque le serveur rencontre une erreur lors de l'exécution de la détection IA, un événement document_error sera envoyé au client websocket. Le client devrait agir de manière appropriée, par exemple une UI affichera un message d'erreur.

Par exemple, le serveur enverra un code d'erreur REQUEST_TIMEOUT lorsqu'il prend plus de 20 secondes à travers les événements chunk.

{
    "event_type": "document_error",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "error_code": "REQUEST_TIMEOUT",
    "message": "Request timeout. Took 20 seconds."
}

Annulations

Il y aura des instances où l'UI voudrait annuler l'opération. L'utilisateur décide de fermer la fenêtre, ou annule l'événement explicitement

Lorsque cela se produit, vous devriez envoyer un événement document_halt

Exemples de réponses

{
    "event_type": "document_halt",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Erreurs

La plupart des erreurs proviendront de paramètres incorrects envoyés à l'API. Vérifiez doublement les paramètres de chaque appel API pour vous assurer qu'il est correctement formaté, et essayez d'exécuter le code d'exemple fourni.

Les codes d'erreur génériques que nous utilisons sont conformes à la norme REST :

Code d'erreurSignification
400Requête invalide -- Votre requête est invalide.
403Interdit -- La clé API est invalide, ou il n'y a pas suffisamment de crédits (0.1 par mot).
404Non trouvé -- La ressource spécifiée n'existe pas.
405Méthode non autorisée -- Vous avez essayé d'accéder à une ressource avec une méthode invalide.
406Non acceptable -- Vous avez demandé un format qui n'est pas JSON.
410Disparu -- La ressource à cet endpoint a été supprimée.
422Corps de requête invalide -- Votre corps de requête est formaté incorrectement ou invalide ou a des paramètres manquants.
429Trop de requêtes -- Vous envoyez trop de requêtes ! Ralentissez !
500Erreur serveur interne -- Nous avons eu un problème avec notre serveur. Réessayez plus tard.
503Service indisponible -- Nous sommes temporairement hors ligne pour maintenance. Veuillez réessayer plus tard.

Problèmes courants et solutions

Problèmes d'authentification

"Échec de vérification utilisateur" (403)

Cause: Clé API invalide ou expirée

Solution:

  1. Vérifiez que votre clé API est correcte
  2. Vérifiez si votre clé API est active dans votre compte
  3. Essayez de régénérer votre clé API

"Pas assez de crédits" (403)

Cause: Crédits insuffisants pour traitement texte

Solution:

  1. Vérifiez vos crédits restants en utilisant /check-user-credits
  2. Achetez des crédits supplémentaires si nécessaire
  3. Utilisez des entrées texte plus courtes pour consommer moins de crédits

Problèmes de validation d'entrée

"Le texte d'entrée ne peut pas être vide" (400)

Cause: Texte vide ou uniquement espaces soumis

Solution:

  1. Assurez-vous que votre entrée texte n'est pas vide
  2. Supprimez tout espace de début/fin
  3. Vérifiez si l'encodage texte est correct

"L'email d'entrée est vide" (400)

Cause: Email manquant pour traitement URL

Solution:

  1. Fournissez une adresse email valide lors de la soumission d'URL
  2. Vérifiez que le format email est correct

Problèmes de traitement

"Timeout de requête" (WebSocket)

Cause: Traitement document a pris trop de temps (>120 secondes)

Solution:

  1. Essayez avec une entrée texte plus petite
  2. Vérifiez si le service connaît une charge élevée
  3. Réessayez la requête

Statut document "failed"

Cause: Traitement a échoué pour diverses raisons

Solution:

  1. Vérifiez si le texte d'entrée répond aux exigences minimales
  2. Vérifiez que le texte est dans un format supporté
  3. Essayez avec un modèle différent
  4. Contactez le support si le problème persiste

Problèmes de connexion WebSocket

Déconnexions

Cause: Problèmes réseau ou déconnexions serveur

Solution:

  1. Vérifiez votre connexion réseau
  2. Implémentez logique de reconnexion
  3. Vérifiez que l'URL WebSocket est correcte

"Utilisateur non trouvé" (WebSocket)

Cause: Organization ID invalide dans connexion WebSocket

Solution:

  1. Vérifiez que l'Organization ID est correct
  2. Assurez-vous que le compte utilisateur est actif
  3. Ré-authentifiez si nécessaire

Besoin d'aide ?

Pour plus d'informations sur l'utilisation de notre API ou pour le support technique, veuillez nous contacter.

Questions fréquemment posées sur l'API

Trouvez des réponses aux questions les plus courantes sur notre API de détection IA.