API de détection d'image IA

1. Obtenir une URL de téléchargement pré-signée

Commencez par demander une URL pré-signée à l'API. Cette URL vous permet de télécharger en toute sécurité votre fichier image sur le serveur de stockage.

GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg

Exemple de requête

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'

Exemple de réponse

{
  "status": "success",
  "presigned_url": "https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

2. Télécharger l'image

Utilisez la 'presigned_url' fournie pour télécharger votre image via une requête PUT. Assurez-vous que le type de contenu correct est défini selon votre format d'image.

Exemple de requête

curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
  --header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg' # Attachment

Assurez-vous que le format de fichier reste cohérent pendant le processus de téléchargement. Un téléchargement réussi renverra un code de statut 200.

3. Soumettre l'image pour détection IA

Après le téléchargement, soumettez l'image pour détection IA en référençant le 'file_path' de l'étape précédente.

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

Exemple de requête

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": false,
  "generate_analysis_details": true
}'

Le 'FILE_PATH' fait référence au chemin obtenu de la réponse dans l'étape initiale, 'Obtenir une URL de téléchargement pré-signée'.

Exemple de réponse

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

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

1. Résultat initial établi (analyse encore en attente)

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

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

2. Continuez à interroger pour les résultats d'analyse

Continuez d'appeler l'endpoint /query avec le même ID d'image. Vérifiez le champ analysis_results_status à chaque réponse. Lorsqu'il passe de 'pending' à 'done', l'objet analysis_results sera rempli.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

3. Analyse terminée — Réponse complète

Une fois que analysis_results_status est 'done', l'objet analysis_results contient l'analyse IA approfondie complète avec niveau d'accord, confiance, indicateurs clés, raisonnement détaillé, motifs visuels et recommandations.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Quand l'analyse n'est pas disponible

Si analysis_results_status est 'skipped', null ou absent, l'analyse approfondie ne sera pas produite pour cette image. Cela se produit lorsque 'generate_analysis_details' n'a pas été défini à 'true' dans la requête /detect, ou pour certains types d'images et scénarios de détection. Vous devez traiter les résultats de détection initiaux comme définitifs.

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

"É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 d'image

Solution:

1. Vérifiez vos crédits restants en utilisant /check-user-credits
2. Achetez des crédits supplémentaires si nécessaire
3. Optimisez la taille de l'image avant téléchargement pour consommer moins de crédits

"Format de fichier non supporté" (400)

Cause: Format d'image non supporté ou invalide soumis

Solution:

1. Vérifiez que le format d'image est supporté (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
2. Assurez-vous que le fichier n'est pas corrompu
3. Vérifiez l'en-tête Content-Type lors du téléchargement

"Fichier trop volumineux" (400)

Cause: La taille du fichier dépasse la limite de 10MB

Solution:

1. Redimensionnez ou compressez l'image à moins de 10MB
2. Vérifiez la taille du fichier avant le téléchargement
3. Utilisez des formats plus efficaces comme WebP lorsque possible

"Timeout de requête" (WebSocket)

Cause: Le traitement d'image a pris trop de temps

Solution:

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

Statut document "failed"

Cause: Le traitement a échoué pour diverses raisons

Solution:

1. Vérifiez si l'image répond aux exigences minimales (1KB - 10MB)
2. Vérifiez que l'image est dans un format supporté
3. Vérifiez que le téléchargement s'est terminé avec succès avant de soumettre pour détection
4. Contactez le support si le problème persiste

"Échec du téléchargement d'image" (403/400)

Cause: URL pré-signée invalide ou expirée, ou problèmes avec le serveur de stockage

Solution:

1. Assurez-vous d'utiliser l'URL pré-signée immédiatement après l'avoir reçue (peut expirer)
2. Vérifiez que l'en-tête Content-Type est correct pour le format d'image
3. Supprimez les espaces du nom de fichier avant le téléchargement
4. Essayez de générer une nouvelle URL pré-signée si la actuelle a expiré

"URL pré-signée invalide" (400)

Cause: Nom de fichier avec espaces ou URL pré-signée expirée/corrompue

Solution:

1. Supprimez tous les espaces du nom de fichier avant de demander une URL pré-signée
2. Utilisez uniquement des caractères alphanumériques, tirets et underscores dans le nom de fichier
3. Générez une nouvelle URL pré-signée si nécessaire