AI Image Detection API

1. Obtain a Pre-signed Upload URL

Begin by requesting a pre-signed URL from the API. This URL allows you to securely upload your image file to the storage server.

For PDF files, only the first image will be detected (single-file flow).

Use a .zip filename on this endpoint when you intend to submit a ZIP via bulk upload.

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

Example Request

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

Example Response

{
  "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"
}

The document_id is a new UUID generated for this upload request (for correlation/logging). The id you use for /detect or /bulk-upload is assigned when you submit those endpoints unless you pass an optional id on /detect.

2. Upload the Image

Use the provided presigned_url to upload your image via a PUT request. Ensure the correct Content-Type is set according to your image format.

Example Request

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'

Additional upload examples (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'

Ensure that the file format remains consistent during the upload process. A successful upload returns HTTP 200.

3. Submit Image for AI Detection

After uploading, submit the image for AI detection by referencing the file_path from the previous step. For PDF uploads, only the first image will be analyzed/detected.

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

Example Request

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

The FILE_PATH refers to the path returned from the presigned-URL step (e.g. uploads/...). Build the full URL with your storage host as shown in the example.

Example Response

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

The response includes a unique image ID for tracking the detection status.

1. Initial result may be ready before analysis

Core detection (result, final_result, confidence) can be done while analysis_results_status is still 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. Keep polling

Call /query with the same id until analysis_results_status changes from 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. Analysis complete

When analysis_results_status is ready, analysis_results includes agreement, imageTags, confidence, keyIndicators, detailedReasoning, visualPatterns, and 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/..."
}

When analysis is not available

If analysis_results_status is skipped, failed, or absent, or generate_analysis_details was false, treat core detection as final.

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

"User verification failed" (403)

Cause: Invalid or expired API key

Solution:

1. Verify your API key is correct
2. Check if your API key is active in your account
3. Try regenerating your API key

"Not enough credits" (403)

Cause: Insufficient credits for image processing

Solution:

1. Check your remaining credits using /check-user-credits
2. Purchase additional credits if needed

"Input URL cannot be empty" (400)

Cause: Empty or invalid URL submitted

Solution:

1. Ensure your url input is not empty
2. Remove leading/trailing whitespace in image names
3. Check URL encoding is correct

"Input email is empty" (400)

Cause: Missing email for URL processing

Solution:

1. Provide a valid email address when submitting URLs
2. Check email format is correct

"Unsupported image type" (400)

Cause: File format not supported

Solution:

1. Convert to a supported format (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
2. Check file extension is correct

"File size is too small" (400)

Cause: Image file is below minimum size requirement

Solution:

1. Use a larger image file (minimum 1KB)
2. Check if the image was corrupted during upload

"File size exceeds limit" (400)

Cause: Image file is too large

Solution:

1. Compress or resize the image; the maximum size is set per deployment (the API error message states the limit in MB)
2. Use a different image format

"Invalid file type" (400)

Cause: File type validation failed

Solution:

1. Ensure the file is a valid image format
2. Check the file is not corrupted
3. Verify MIME type matches file extension

Image status "failed"

Cause: Processing failed for various reasons

Solution:

1. Verify URL is in a supported format
2. Check the image file is valid and not corrupted
3. Ensure the image meets size requirements
4. Contact support if the issue persists

"User not found"

Cause: Invalid user ID

Solution:

1. Verify user ID is correct
2. Ensure user account is active
3. Re-authenticate if needed

"File metadata could not be fetched" (500)

Cause: Unable to access uploaded file

Solution:

1. Verify file was uploaded successfully
2. Check file URL is accessible
3. Try re-uploading the file

"Image upload failed" (403/400)

Cause: Invalid or expired pre-signed URL, or issues with the storage server

Solution:

1. Use the pre-signed URL promptly after receiving it
2. Verify Content-Type matches the file format
3. Remove spaces from the filename before upload
4. Generate a new pre-signed URL if needed

"Invalid pre-signed URL" (400)

Cause: Filename with spaces or expired/corrupted pre-signed URL

Solution:

1. Remove spaces from the filename before requesting a pre-signed URL
2. Use alphanumeric characters, hyphens, and underscores
3. Generate a new pre-signed URL if needed

"URL must point to a ZIP file" (400)

Cause: The URL provided to /bulk-upload does not point to a ZIP file

Solution:

1. Use get-presigned-url?file_name=images.zip (or another .zip filename)
2. Upload a valid ZIP to the presigned URL
3. Ensure the bulk-upload request url points to that uploaded ZIP

"ZIP file too large" (400)

Cause: ZIP exceeds maximum size (100MB)

Solution:

1. Reduce the number of images or compress them
2. Split into multiple bulk uploads

"Too many files" (400)

Cause: ZIP contains more than 50 valid images

Solution:

1. Reduce to 50 or fewer images per ZIP
2. Split into multiple bulk uploads

"No valid images found in ZIP" (400)

Cause: All files in the ZIP were skipped (unsupported format, too small, invalid path, etc.)

Solution:

1. Use supported formats (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
2. PDF is not supported in bulk
3. Each image must be at least 1KB and at most 10MB
4. Avoid hidden files (names starting with .) and path traversal (..)

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

Cause: The id does not match that upload type (single image vs ZIP batch)

Solution:

1. Use the id from /detect for single-image submissions
2. Use the id from /bulk-upload for ZIP submissions