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
}'

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

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,
    "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
    },
    "status": "done",
    "retry_count": 0
}

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
}

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.

Contactez-nous

Questions fréquemment posées sur l'API

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