AI Image Detection

Endpoint Overview

POST /api/v1/ocr/ai-image-detection

Description

This endpoint analyzes a submitted image to detect whether it was generated by an AI model or manipulated using deepfake techniques. Submit an image file along with a detection model selector, and receive a structured response containing an AI-generated probability score, a deepfake score, detected AI generator signals, and metadata about the submitted media.

The API is designed to support fraud detection, identity verification, and content integrity workflows where distinguishing between authentic photographs and AI-synthesized or manipulated images is critical. Results are returned synchronously with numeric confidence scores, enabling your application to enforce thresholds, route submissions to manual review, or reject potentially fraudulent media automatically.

Key Benefits

Returns a numeric ai_generated_score between 0 and 1, providing a calibrated probability rather than a binary flag — giving your application full control over threshold-based decisioning

Detects both fully AI-generated images and deepfake manipulations via separate ai_generated_score and deepfake_score fields, covering a broader spectrum of synthetic media threats

Exposes ai_generators signals to surface which AI generation tools or fingerprints were detected in the image, enabling more granular fraud intelligence

Supports model selection via the model parameter, allowing you to choose the detection approach best suited to your use case

Use Cases

KYC & Identity Verification

Insurance & Claims

Content & Media Platforms

Detect AI-generated or deepfake selfies submitted during remote KYC onboarding to prevent identity fraud before an account is created

Flag synthetic face images uploaded as profile photos or liveness check submissions in digital banking and fintech applications

Automatically reject document selfie pairs where the face image scores above a defined ai_generated_score threshold, routing borderline cases to human review

Strengthen video KYC workflows by screening captured frames for deepfake indicators before approving high-value identity verifications

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
`Authorization`	Yes	JWT Bearer token. Format: `Bearer <YOUR_JWT_TOKEN>`. Use the sandbox token for sandbox and the production token for production.
`Content-Type`	Yes	Must be set to `multipart/form-data`. Required because the request includes a file upload alongside form fields. Do not set this manually in most HTTP clients — it is set automatically with the correct multipart boundary.

Request Body

This endpoint accepts a multipart/form-data request body containing a file upload and a model selector field.

Parameter	Type	Required	Description
`file`	file	Yes	The image file to be analyzed for AI generation or deepfake manipulation. Submit as a binary file part with content type `application/octet-stream`.
`model`	string	Yes	The detection model to use for analysis. Pass `"genai"` to use the generative AI detection model, `"deepfake"` to use the Deepfake detection model or `"combined"` to use all the Models

Example Request

Process Response

Response Parameters

Parameter	Type	Description
`data`	object	Contains the AI image detection result payload for this request.
`data.client_id`	string	A server-generated unique session identifier for this detection request. Useful for support queries and audit logging.
`data.model`	string	The detection model used to analyze the submitted image, reflecting the `model` value passed in the request (e.g., `"genai"`).
`data.ai_generated_score`	number	A probability score between 0 and 1 indicating the likelihood that the submitted image was generated by an AI model. Values closer to 1 indicate a higher probability of AI generation.
`data.deepfake_score`	number \| null	A probability score between 0 and 1 indicating the likelihood that the submitted image has been deepfake-manipulated. Returns `null` when deepfake analysis is not applicable or not performed for the selected model.
`data.ai_generators`	object	An object containing signals or fingerprints identifying specific AI generation tools detected in the image. Returns an empty object `{}` if no specific generators are identified.
`data.media_uri`	string	The filename or URI of the submitted media file as received by the server.
`data.type`	object	An object summarizing the detection type scores. Contains `ai_generated` as a key with its corresponding probability score as the value.
`data.type.ai_generated`	number	The AI-generated probability score, mirroring the value in `data.ai_generated_score`.
`data.media`	object	An object containing metadata about the submitted media.
`data.media.uri`	string	The filename or URI of the submitted media file, mirroring the value in `data.media_uri`.
`status_code`	integer	HTTP-equivalent numeric status code. `200` indicates successful processing.
`success`	boolean	Top-level flag indicating whether the request was processed successfully. `true` on success.
`message`	string	Human-readable status message. Returns `"Success"` on successful processing.
`message_code`	string	Machine-readable message identifier for programmatic response handling. Returns `"success"` on success.

Example Successful Response

{
  "data": {
    "client_id": "ocr_ai_image_detection_zjibQobuHPwKdsoekjOo",
    "model": "genai",
    "ai_generated_score": 0.001,
    "deepfake_score": null,
    "ai_generators": {},
    "media_uri": "image.png",
    "type": {
      "ai_generated": 0.001
    },
    "media": {
      "uri": "image.png"
    }
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

401 Unauthorized

400 Bad Request

422 Unprocessable Entity

429 Rate Limited

500 Server Error

{
  "data": null,
  "status_code": 401,
  "success": false,
  "message": "Unauthorized",
  "message_code": "unauthorized"
}

Returned when the Authorization header is missing, malformed, or the JWT token is expired or invalid. Verify that a valid Bearer token for the correct environment (sandbox or production) is included in the request.

Integration Best Practices

Security Recommendations

Never hardcode JWT tokens in client-side code or version control — use environment variables or a secrets manager

Transmit image files exclusively over HTTPS; never send potentially sensitive media over unencrypted HTTP

Do not retain submitted images on your servers beyond the time required for processing — delete them immediately after extracting scores in accordance with your data retention policy

Keep sandbox and production JWT tokens strictly separate — never use a production token in development or testing environments

Restrict API key access using IP allowlisting or access controls where supported to limit exposure in case of token compromise

User Experience Guidelines

Define and document your ai_generated_score acceptance threshold before going live — a commonly used starting point is to reject scores above 0.8, flag scores between 0.5 and 0.8 for manual review, and auto-approve scores below 0.5; calibrate based on your risk tolerance

When deepfake_score is null, do not surface this as an error to users — it simply means deepfake analysis was not applicable for the selected model or image type

Provide clear, non-technical messaging when an image is rejected due to a high AI-generated score, and give users a straightforward path to re-submit a different image rather than a generic failure screen

Validate file type and size on the client side before upload to catch unsupported formats early and reduce unnecessary API calls

Log client_id values alongside submission metadata to enable traceability and support investigations for flagged submissions

Code Samples

cURL

Python

Node.js

Related APIs

Face Match API: Compare two face images for similarity — commonly used alongside AI Image Detection to verify that a submitted selfie is both a genuine photograph and matches a reference identity document

Liveness Detection API: Detect whether a face in an image or video is from a live person or a spoofed source — pairs naturally with AI Image Detection to provide layered anti-spoofing coverage during KYC

PAN Advanced OCR API: Extract structured data from PAN card images — often used in the same onboarding pipeline where AI Image Detection is applied to the accompanying selfie or document photo

Aadhaar OCR API: Extract identity fields from Aadhaar card images — combine with AI Image Detection to validate that the submitted Aadhaar document image has not been synthetically generated or manipulated

Compliance and Legal Considerations

AI-generated image detection produces probabilistic scores, not definitive determinations. Automated rejection of users based solely on a high ai_generated_score may constitute an adverse action. Implement a human review step for borderline cases, particularly in regulated KYC, lending, or insurance workflows.

Collection and processing of facial images and biometric data is governed by the Digital Personal Data Protection Act, 2023 (DPDPA) in India. Ensure explicit, informed consent is obtained from individuals before submitting their images to this API.

If this API is used as part of a KYC workflow in a regulated industry, ensure its use is compliant with the applicable regulator's guidelines (RBI, IRDAI, SEBI, etc.) regarding automated identity verification and document authenticity checks.

Do not retain submitted images beyond the minimum period required for processing. Implement a clear data deletion policy and ensure it is reflected in your organization's privacy notice.

Surepass acts as a data processor. Your organization retains responsibility as the data controller for ensuring all image processing activities are lawful, purposeful, and disclosed to affected individuals.

Be transparent with users when image analysis is being performed as part of your onboarding or verification flow — failure to disclose automated processing of biometric data may violate applicable privacy regulations.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

{ "data": { "client_id": "ocr_ai_image_detection_zjibQobuHPwKdsoekjOo", "model": "genai", "ai_generated_score": 0.001, "deepfake_score": null, "ai_generators": {}, "media_uri": "image.png", "type": { "ai_generated": 0.001 }, "media": { "uri": "image.png" } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses