API de détection d'images par IA

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

Commencez par demander une URL pré-signée à l'API. Elle permet de téléverser votre fichier image de façon sécurisée vers le serveur de stockage.

Pour les fichiers PDF, seule la première image sera détectée (flux fichier unique).

Utilisez un nom de fichier .zip sur cet endpoint lorsque vous préparez un envoi ZIP en masse.

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://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...",
  "file_path": "uploads/example.jpg",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Le document_id est un nouvel UUID généré pour cette demande de téléversement (corrélation / journaux). L'id utilisé pour /detect ou /bulk-upload est attribué lors de la soumission de ces endpoints, sauf si vous passez un id facultatif sur /detect.

2. Téléverser l'image

Utilisez le presigned_url fourni pour téléverser votre image via une requête PUT. Assurez-vous que le Content-Type correspond au format de votre image.

Exemple de requête

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...' \
  --header 'Content-Type: image/jpeg' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg'

Exemples de téléversement supplémentaires (PNG, PDF, SVG)

curl -X PUT '<PRESIGNED_URL_FOR_example.png>' \
  --header 'Content-Type: image/png' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.png'

curl -X PUT '<PRESIGNED_URL_FOR_example.pdf>' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.pdf'

curl -X PUT '<PRESIGNED_URL_FOR_example.svg>' \
  --header 'Content-Type: image/svg+xml' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.svg'

Le format du fichier doit rester cohérent pendant le téléversement. Un téléversement réussi renvoie HTTP 200.

3. Soumettre l'image pour détection IA

Après le téléversement, soumettez l'image pour détection en vous référant au file_path de l'étape précédente. Pour les PDF, seule la première image sera analysée / détectée.

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": true
}'

FILE_PATH désigne le chemin renvoyé à l'étape URL pré-signée (p. ex. uploads/...). Construisez l'URL complète avec votre hôte de stockage comme dans l'exemple.

Exemple de réponse

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

La réponse inclut un identifiant d'image unique pour suivre l'état de la détection.

1. Le résultat initial peut être prêt avant l'analyse

La détection principale (result, final_result, confidence) peut être disponible pendant que analysis_results_status est encore pending.

{
    "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. Poursuivre l'interrogation

Appelez /query avec le même id jusqu'à ce que analysis_results_status change par rapport à pending.

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

Lorsque analysis_results_status vaut ready, analysis_results inclut agreement, imageTags, confidence, keyIndicators, detailedReasoning, visualPatterns et recommendations.

{
    "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": {
            "imageTags": [
                "person",
                "portrait",
                "outdoor",
                "vineyard",
                "smiling"
            ],
            "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/..."
}

Lorsque l'analyse n'est pas disponible

Si analysis_results_status vaut skipped, failed ou est absent, ou si generate_analysis_details était false, considérez la détection principale comme définitive.

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

« User verification failed » (403)

Cause: Clé API invalide ou expirée

Solution:

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

« Not enough credits » (403)

Cause: Crédits insuffisants pour le traitement d'image

Solution:

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

« Input URL cannot be empty » (400)

Cause: URL vide ou invalide soumise

Solution:

1. Assurez-vous que l'entrée url n'est pas vide
2. Supprimez les espaces en début et fin dans les noms d'image
3. Vérifiez l'encodage de l'URL

« Input email is empty » (400)

Cause: E-mail manquant pour le traitement d'URL

Solution:

1. Fournissez une adresse e-mail valide lors de la soumission d'URL
2. Vérifiez le format de l'e-mail

« Unsupported image type » (400)

Cause: Format de fichier non pris en charge

Solution:

1. Convertissez vers un format pris en charge (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
2. Vérifiez que l'extension du fichier est correcte

« File size is too small » (400)

Cause: Fichier image en dessous de la taille minimale

Solution:

1. Utilisez une image plus grande (minimum 1 Ko)
2. Vérifiez que l'image n'a pas été corrompue pendant le téléversement

« File size exceeds limit » (400)

Cause: Fichier image trop volumineux

Solution:

1. Compressez ou redimensionnez l'image ; la limite maximale dépend du déploiement (le message d'erreur de l'API indique la limite en Mo)
2. Utilisez un autre format d'image

« Invalid file type » (400)

Cause: Échec de la validation du type de fichier

Solution:

1. Assurez-vous que le fichier est un format image valide
2. Vérifiez que le fichier n'est pas corrompu
3. Vérifiez que le type MIME correspond à l'extension

Statut d'image « failed »

Cause: Échec du traitement pour diverses raisons

Solution:

1. Vérifiez que l'URL est dans un format pris en charge
2. Contrôlez que le fichier image est valide et non corrompu
3. Assurez-vous que l'image respecte les exigences de taille
4. Contactez le support si le problème persiste

« User not found »

Cause: Identifiant utilisateur invalide

Solution:

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

« File metadata could not be fetched » (500)

Cause: Impossible d'accéder au fichier téléversé

Solution:

1. Vérifiez que le fichier a bien été téléversé
2. Contrôlez que l'URL du fichier est accessible
3. Réessayez de téléverser le fichier

« Image upload failed » (403/400)

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

Solution:

1. Utilisez l'URL pré-signée rapidement après réception
2. Vérifiez que le Content-Type correspond au format du fichier
3. Supprimez les espaces du nom de fichier avant le téléversement
4. Générez une nouvelle URL pré-signée si nécessaire

« Invalid pre-signed URL » (400)

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

Solution:

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

« URL must point to a ZIP file » (400)

Cause: L'URL fournie à /bulk-upload ne pointe pas vers un fichier ZIP

Solution:

1. Utilisez get-presigned-url?file_name=images.zip (ou un autre nom .zip)
2. Téléversez un ZIP valide vers l'URL pré-signée
3. Assurez-vous que l'url de bulk-upload pointe vers ce ZIP téléversé

« ZIP file too large » (400)

Cause: Le ZIP dépasse la taille maximale (100 Mo)

Solution:

1. Réduisez le nombre d'images ou compressez-les
2. Répartissez sur plusieurs envois groupés

« Too many files » (400)

Cause: Le ZIP contient plus de 50 images valides

Solution:

1. Limitez à 50 images ou moins par ZIP
2. Répartissez sur plusieurs envois groupés

« No valid images found in ZIP » (400)

Cause: Tous les fichiers du ZIP ont été ignorés (format non pris en charge, trop petit, chemin invalide, etc.)

Solution:

1. Utilisez des formats pris en charge (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
2. Le PDF n'est pas pris en charge en masse
3. Chaque image doit faire au moins 1 Ko et au plus 10 Mo
4. Évitez les fichiers cachés (noms commençant par .) et la traversée de répertoire (..)

« Document is not a bulk upload (image-zip) result » (400)

Cause: L'id ne correspond pas à ce type de téléversement (image unique vs lot ZIP)

Solution:

1. Utilisez l'id renvoyé par /detect pour les soumissions fichier unique
2. Utilisez l'id renvoyé par /bulk-upload pour les soumissions ZIP