Image Analysis Upload API

Endpoint Overview

POST /api/v1/image-analysis/upload

Description

The Image Analysis Upload API provides advanced computer vision capabilities to analyze uploaded images for face coverage detection and blur assessment. This endpoint processes image files to determine whether faces in the image are covered (masked, obscured, or hidden) and whether the image quality meets clarity standards by detecting blur levels.

This API is essential for identity verification workflows, security applications, and quality assurance processes where face visibility and image clarity are critical requirements.

Key Benefits

Real-time Analysis: Instant processing of uploaded images with immediate results

Dual Detection: Simultaneously checks for face coverage and image blur

Configurable Thresholds: Customizable face coverage detection sensitivity

High Accuracy: Advanced computer vision algorithms for reliable detection

Use Cases

Identity Verification

Security & Access Control

Quality Assurance

KYC (Know Your Customer) processes requiring clear face visibility

Document verification where face photos must be unobscured

Account registration with photo ID requirements

Age verification systems requiring facial analysis

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	Bearer token for API authentication (JWT)
Content-Type	Yes	Must be set to `multipart/form-data` for file upload

Request Body

Parameter	Type	Required	Description
file	File	Yes	Image file to analyze (JPEG, PNG, WebP formats supported)
face_coverage_threshold	String	No	Sensitivity threshold for face coverage detection (0-50, default: 5)

Example Request

Process Response

Response Parameters

Parameter	Type	Description
success	Boolean	Indicates whether the API call was successful
status_code	Integer	HTTP status code of the response
message	String	Human-readable message describing the result
message_code	String	Machine-readable code for the result status
data	Object	Container for the analysis results
data.client_id	String	Unique identifier for this analysis request
data.is_blurred	Boolean	Whether the uploaded image is detected as blurred
data.is_face_covered	Boolean	Whether faces in the image are detected as covered

Example Successful Response

{
    "data": {
        "client_id": "image_analysis_mTVfQzulBJDfgPhzzloE",
        "is_blurred": false,
        "is_face_covered": true
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid File Format

File Size Error

{
    "success": false,
    "status_code": 401,
    "message": "Authentication failed",
    "message_code": "auth_error",
    "data": null
}

Occurs when the Bearer token is missing, invalid, or expired.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and implement token refresh mechanisms

Use HTTPS for all API communications to protect sensitive image data

Implement proper error handling to avoid exposing sensitive information

Validate file types and sizes on the client side before uploading

Consider implementing rate limiting to prevent abuse

User Experience Guidelines

Provide clear feedback about image quality requirements to users

Implement progress indicators for file upload operations

Display helpful error messages when images fail analysis

Allow users to retake or re-upload images when analysis fails

Consider showing preview of uploaded images before processing

Code Samples

cURL

Python

Node.js

Related APIs

Document OCR API: Extract text and data from identity documents with face matching capabilities

Face Comparison API: Compare faces between multiple images for identity verification

Liveness Detection API: Detect whether a face image is from a live person or a photo/video

ID Document Verification API: Comprehensive document authenticity and data extraction services

Compliance and Legal Considerations

Ensure compliance with local privacy laws (GDPR, CCPA, etc.) when processing facial images

Implement proper data retention and deletion policies for uploaded images

Obtain necessary user consent before processing biometric data

Consider regulations around face recognition technology in your jurisdiction

Maintain audit logs of image analysis activities for compliance purposes

Be transparent about face coverage and blur detection capabilities in your privacy policy

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "image_analysis_mTVfQzulBJDfgPhzzloE", "is_blurred": false, "is_face_covered": true }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Upload

Image Analysis Upload API#

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