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.

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://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

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://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

Ensure that the file format remains consistent during the upload process. A successful upload will return a status code of 200.

3. Submit Image for AI Detection

After uploading, submit the image for AI detection by referencing the 'file_path' from the previous step.

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

The 'FILE_PATH' refers to the path obtained from the response in the initial step, 'Obtain a Pre-signed Upload URL'.

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 Settles (Analysis Still Pending)

When you submit with 'generate_analysis_details': true and first query with status 'done', the core detection results (result, final_result, confidence) are ready. However, analysis_results_status may be 'pending' — this means the deep AI analysis is still processing in the background.

{
    "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 for Analysis Results

Continue calling the /query endpoint with the same image ID. Check the analysis_results_status field on each response. When it changes from 'pending' to 'done', the analysis_results object will be populated.

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 — Full Response

Once analysis_results_status is 'done', the analysis_results object contains the full deep AI analysis with agreement level, confidence, key indicators, detailed reasoning, visual patterns, 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": {
            "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', null, or absent, deep analysis will not be produced for this image. This happens when 'generate_analysis_details' was not set to 'true' in the /detect request, or for certain image types and detection scenarios. You should treat the initial detection results 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
3. Optimize image size before upload to consume fewer credits

"Unsupported file format" (400)

Cause: Unsupported or invalid image format submitted

Solution:

1. Verify image format is supported (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
2. Ensure the file is not corrupted
3. Check Content-Type header when uploading

"File too large" (400)

Cause: File size exceeds 10MB limit

Solution:

1. Resize or compress the image to under 10MB
2. Check file size before uploading
3. Use more efficient formats like WebP when possible

"Request timeout" (WebSocket)

Cause: Image processing took too long

Solution:

1. Try with a smaller or less complex image
2. Check if the service is experiencing high load
3. Retry the request

Document Status "failed"

Cause: Processing failed for various reasons

Solution:

1. Check if image meets minimum requirements (1KB - 10MB)
2. Verify image is in a supported format
3. Verify upload completed successfully before submitting for detection
4. Contact support if issue persists

"Image upload failed" (403/400)

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

Solution:

1. Ensure you use the pre-signed URL immediately after receiving it (may expire)
2. Verify Content-Type header is correct for image format
3. Remove spaces from filename before uploading
4. Try generating a new pre-signed URL if the current one expired

"Invalid pre-signed URL" (400)

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

Solution:

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