Articles on: Developer API

Image Detector API


Try it Out


You can test out the API without code by going to the FastAPI link with your web browser: https://ai-image-detect.undetectable.ai/docs


Authentication


Undetectable.AI uses API keys to allow access to the API. You can get your API key at the top of the page in our developer portal.


UD expects for the API key to be included in all API requests to the server in a request body that looks like the following:


key: YOUR API KEY GOES HERE


You must replace YOUR API KEY GOES HERE with your personal API key.


AI Image Detector


Detect (3-Step Process)


The AI Image Detection workflow consists of the following steps:


  • Obtain a Pre-signed Upload URL
  • Upload the Image
  • Submit the Image for Detection


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.


Supported File Formats: JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF


Note: It is necessary to remove spaces from the image filename when requesting a pre-signed URL.


**GET ** https://ai-image-detect.undetectable.ai/get-presigned-url?file_name=example.jpg


Example Request


curl -X GET 'https://ai-image-detect.undetectable.ai/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"
}


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/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
--header 'x-amz-acl: private' \
--data-binary '@example.jpg' # Attachment

Note: It is necessary to remove spaces from the image filename when uploading the image.


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


File Size Limits:

  • Minimum file size: 1KB
  • Maximum file size: 10MB


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://ai-image-detect.undetectable.ai/detect


Example Request


curl -X 'POST' \
'https://ai-image-detect.undetectable.ai/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
}'

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


Optional Parameters:

  • generate_preview: Set to true to generate a preview URL for the image (default: false)
  • document_type: Type of document (default: Image)
  • email: Email address for processing


Example Response


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


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


Query Detection Status and Results


To check the status and retrieve the results, use the /query endpoint with the image ID.


**POST ** https://ai-image-detect.undetectable.ai/query


Example Request


curl -X 'POST' \
'https://ai-image-detect.undetectable.ai/query' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"id": "IMAGE-ID-GOES-HERE"
}'


Example Response


{
"id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
"status": "done",
"result": 90.2371538185235,
"result_details": {
"is_valid": true,
"detection_step": 3,
"final_result": "AI Generated",
"metadata": [
"No Information Detected for Real/AI",
"Could not find anything from ExifTool and Pillow metadata"
],
"ocr": [
"OCR did not detect AI",
0.0
],
"ml_model": [
"AI Generated",
90.2371538185235
],
"confidence": 90.2371538185235
},
"preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}


Result Details


  • is_valid: Indicates if the image file is valid (true/false)
  • detection_step: Indicates the stage at which detection was completed.
  • 1: Only metadata is returned.
  • 2: Returns metadata and ocr results.
  • 3: Returns metadata, ocr, and ml_model results.
  • final_result: The overall determination (e.g., "AI Generated", "Not AI Generated").
  • confidence: The confidence score of the detection.
  • metadata: Information extracted from image metadata using ExifTool and Pillow.
  • ocr: Results from Optical Character Recognition analysis for watermark detection.
  • ml_model: Results from the machine learning model (ConvNeXt-based classifier).
  • preview_url: URL to the preview image (if generate_preview was set to true).


The status field will be one of:

  • pending: Processing is queued
  • analyzing: AI detection is in progress
  • done: Results are available
  • failed: Processing failed



Check User Credits


This endpoint accepts the users apikey via the header. And returns users credit details.


**GET ** https://ai-image-detect.undetectable.ai/check-user-credits


Example Request


curl -X 'GET' \
'https://ai-image-detect.undetectable.ai/check-user-credits' \
-H 'apikey: YOUR API KEY GOES HERE' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \


Example Response


{
"baseCredits": 10000,
"boostCredits": 1000,
"credits": 11000
}


Note: For external integrations, only the credits field will be populated.



Health Check


Check the health status of the API server.


**GET ** https://ai-image-detect.undetectable.ai/health


Example Request


curl -X 'GET' \
'https://ai-image-detect.undetectable.ai/health' \
-H 'accept: application/json'


Example Response


{
"status": "healthy"
}


Errors


Most errors will be from incorrect parameters being sent to the API. Double check the parameters of each API call to make sure it's properly formatted, and try running the provided example code.


The generic error codes we use conform to the REST standard:


Error Code

Meaning

400

Bad Request -- Your request is invalid.

403

Forbidden -- The API key is invalid, or there aren't sufficient credits (0.1 per word).

404

Not Found -- The specified resource doesn't exist.

405

Method Not Allowed -- You tried to access a resource with an invalid method.

406

Not Acceptable -- You requested a format that isn't JSON.

410

Gone -- The resource at this endpoint has been removed.

422

Invalid Request Body -- Your request body is formatted incorrectly or invalid or has missing parameters.

429

Too Many Requests -- You're sending too many requests! Slow it down!

500

Internal Server Error -- We had a problem with our server. Try again later.

503

Service Unavailable -- We're temporarily offline for maintenance. Please try again later.


Common Issues and Solutions


Authentication Issues


"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 Validation Issues


"Input URL cannot be empty" (400)

  • Cause: Empty or invalid URL submitted
  • Solution:


  1. Ensure your url input is not empty
  2. Remove any leading/trailing whitespace in image names
  3. Check if 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 image to supported format (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF)
  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 image was corrupted during upload


"File size exceeds limit" (400)

  • Cause: Image file is too large
  • Solution:


  1. Compress or resize image (maximum 50MB)
  2. Use a different image format


"Invalid file type" (400)

  • Cause: File type validation failed
  • Solution:


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


Processing Issues


Image Status "failed"

  • Cause: Processing failed for various reasons
  • Solution:


  1. Verify URL is in a supported format
  2. Check image file is valid and not corrupted
  3. Ensure image meets size requirements
  4. Contact support if 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


Updated on: 29/07/2025

Was this article helpful?

Share your feedback

Cancel

Thank you!