Documentation de l'API
ISO 27001SOC 2 CertifiedGDPR Compliant

API de détection vidéo IA

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

Essayez sans code en visitant notre endpoint FastAPI : https://detect-video.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.

Détecteur vidéo IA

Détecter (processus en 2 étapes)

Le workflow de détection vidéo IA consiste en les étapes suivantes :

  • Soumettre la vidéo pour détection (multipart upload)
  • Interroger le travail pour récupérer résultats

1. Soumettre la vidéo pour détection

Téléchargez un fichier vidéo directement vers l'API. Le serveur validera le fichier.

Formats de fichiers supportés

MP4, MOV, AVI, MKV, WEBM

Limites de taille de fichier

  • Taille minimale de fichier : 1KB
  • Taille maximale de fichier : 100MB
POST https://detect-video.truthscan.com/detect-file

Exemple de requête

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

Paramètres optionnels

  • document_type: Type de document (par défaut : 'Video')
  • email: Adresse email optionnelle pour traitement

Exemple de réponse

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

La réponse inclut un ID vidéo unique pour suivre le statut de détection.

2. Interroger le statut et résultats de détection

Après soumission, interrogez l'endpoint /query avec l'ID du travail pour récupérer statut et résultats.

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

Exemple de requête

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

Exemple de réponse

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

Détails des résultats

  • status: "pending", "analyzing", "done", ou "failed"
  • result: Score scalaire en [0.0, 1.0] dérivé de ML prob_fake
  • final_stage: Dernière étape qui a contribué au résultat : 'metadata', 'watermark' ou 'ml'
  • metadata: Définit toujours prediction : 'no_detection' et confidence : 0.0. Status peut être 'reject', 'reencode' ou 'ok'
  • watermark: Heuristique qui échantillonne frames et calcule confiance pseudo à partir variance pixels
  • ml: Classificateur basé ConvNeXt exécuté sur frames échantillonnés. Retourne prob_fake en [0.0, 1.0] et label ('ai_generated' si prob_fake ≥ 0.5, sinon 'no_detection')
  • latency_sec: Temps total pipeline

Le champ "status" sera l'un de : "pending" (traitement en file d'attente), "analyzing" (détection IA en cours), "done" (résultats disponibles), ou "failed" (traitement échoué).

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-video.truthscan.com/check-user-credits

Exemple de requête

curl -X 'GET' \
  'https://detect-video.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
}

Vérification de santé

Vérifier le statut de santé du serveur API.

GET https://detect-video.truthscan.com/health

Exemple de requête

curl -X 'GET' \
  'https://detect-video.truthscan.com/health' \
  -H 'accept: application/json'

Exemple de réponse

{
    "status": "healthy"
}

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 pour le traitement vidéo.
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 vidéo

Solution:

  1. Vérifiez vos crédits restants en utilisant /check-user-credits
  2. Achetez des crédits supplémentaires si nécessaire

Problèmes de validation d'entrée

"Type vidéo non supporté" (400)

Cause: Format de fichier non supporté

Solution:

  1. Convertissez la vidéo en format supporté (MP4, MOV, AVI, MKV, WEBM)
  2. Assurez-vous que l'extension fichier et type MIME sont corrects

"Taille fichier dépasse limite" (400)

Cause: Fichier vidéo trop volumineux

Solution:

  1. Compressez, coupez ou ré-encodez la vidéo pour réduire taille (maximum 100MB)
  2. Utilisez codec/container plus efficace

"Taille fichier trop petite" (400)

Cause: Fichier vidéo en dessous exigence taille minimale

Solution:

  1. Utilisez fichier vidéo plus grand (minimum 1KB)
  2. Vérifiez si fichier a été corrompu pendant téléchargement

"Type fichier invalide" (400)

Cause: Validation type fichier échouée (par ex., type MIME incorrect ou fichier corrompu)

Solution:

  1. Assurez-vous que fichier est format vidéo valide
  2. Vérifiez que type MIME correspond extension fichier
  3. Ré-exportez ou ré-encodez fichier si nécessaire

Problèmes de traitement

Statut vidéo "failed"

Cause: Traitement échoué (par ex., container illisible, erreurs décodage)

Solution:

  1. Assurez-vous que container/codec est communément supporté (H.264/AAC en MP4 recommandé)
  2. Ré-encodez vidéo en utilisant preset standard (par ex., ffmpeg) et ré-téléchargez
  3. Assurez-vous que fichier répond exigences taille et format

Statut vidéo "timeout" ou traitement long

Cause: Traitement vidéo prend plus longtemps que prévu ou a expiré

Solution:

  1. Attendez un peu plus et vérifiez statut à nouveau en utilisant /query
  2. Assurez-vous que fichier vidéo répond toutes exigences format et taille
  3. Contactez support si problème persiste

"Utilisateur non trouvé"

Cause: ID utilisateur invalide

Solution:

  1. Vérifiez que votre clé API est correcte et liée à compte actif
  2. Assurez-vous que utilisateur intégration est valide et actif
  3. Ré-authentifiez si nécessaire

"Métadonnées fichier n'ont pas pu être récupérées" (500)

Cause: Impossible d'accéder ou parser fichier téléchargé

Solution:

  1. Vérifiez que téléchargement s'est terminé avec succès
  2. Vérifiez que fichier est accessible et non corrompu
  3. Essayez de ré-télécharger fichier

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 vidéo IA.