API Documentation

Integrate our powerful photo assessment and processing capabilities into your applications.

Face Image Quality Assessment API

Endpoint: /v1/assess

This API assesses the quality of a given face image based on the ISO/IEC 29794-5 standard. It provides a detailed JSON report with various quality metrics, enabling you to ensure compliance and optimal image quality for biometric applications.

Request Details

Method:
POST
Content-Type:
multipart/form-data
Parameters:
- file: The image file to assess (e.g., PNG, JPG). This is a required field.

Example (cURL):

Shell

1
2
curl --location 'https://api.visaphoto.de/v1/assess' \
--form 'file=@"/path/to/image.png"'

Response (JSON)

A successful request returns a JSON object containing various quality scores. Each score ranges from 0 to 100, where higher values generally indicate better quality or compliance for that specific metric.

Example Response:

JSON

1
2
3
4
5
6
7
8
{
    "UnifiedQualityScore": 66.0,
    "BackgroundUniformity": 82.0,
    "IlluminationUniformity": 70.0,
    // ... (other fields as provided)
    "ExpressionNeutrality": 99.0,
    "NoHeadCoverings": 100.0
}

Response Fields

The following table details the fields returned in the JSON response:

Field Name	Description
UnifiedQualityScore	Overall quality score of the face image.
BackgroundUniformity	Score for the uniformity of the background.
IlluminationUniformity	Score for the uniformity of illumination on the face.
LuminanceMean	Mean luminance value of the image.
LuminanceVariance	Variance in luminance across the image.
UnderExposurePrevention	Score indicating prevention of under-exposure.
OverExposurePrevention	Score indicating prevention of over-exposure.
DynamicRange	Score for the dynamic range of the image.
Sharpness	Sharpness score of the facial features.
CompressionArtifacts	Score indicating absence of compression artifacts.
NaturalColour	Score for natural skin tone color.
SingleFacePresent	Score indicating a single face is present.
EyesOpen	Score indicating both eyes are open.
MouthClosed	Score indicating the mouth is closed.
EyesVisible	Score indicating eyes are clearly visible (e.g., not covered by hair).
MouthOcclusionPrevention	Score indicating no occlusion of the mouth area.
FaceOcclusionPrevention	Score indicating no occlusion of the face (e.g., by hands, objects).
InterEyeDistance	Score related to the distance between the eyes, relevant for resolution.
HeadSize	Score for the appropriate size of the head within the frame.
LeftwardCropOfTheFaceImage	Score for correct cropping on the left side of the face.
RightwardCropOfTheFaceImage	Score for correct cropping on the right side of the face.
MarginAboveOfTheFaceImage	Score for appropriate margin above the head.
MarginBelowOfTheFaceImage	Score for appropriate margin below the chin.
HeadPoseYaw	Score for acceptable head yaw (left/right turn).
HeadPosePitch	Score for acceptable head pitch (up/down tilt).
HeadPoseRoll	Score for acceptable head roll (sideways tilt).
ExpressionNeutrality	Score for a neutral facial expression.
NoHeadCoverings	Score indicating absence of head coverings (unless for religious/medical reasons, context dependent).

Image Processing & Enhancement API

Endpoint: /v1/process

This API attempts to process a raw image to make it compliant with ISO/IEC 29794-5 standards. This includes operations like background removal, auto-cropping, and centering. After processing, it internally runs an assessment using the same logic as the /v1/assess endpoint.

Important Note: This is a trial/attempt-based service. While it aims to make images compliant, success is not guaranteed. The quality of the output heavily depends on the input image quality.

Request Details

Method:
POST
Content-Type:
multipart/form-data
Parameters:
- file: The image file to process (e.g., PNG, JPG). This is a required field.

Example (cURL):

Shell

1
2
curl --location 'https://api.visaphoto.de/v1/process' \
--form 'file=@"/path/to/image.png"'

Response

If successful: The API returns the processed image file (e.g., image/png, image/jpeg). The Content-Type header will indicate the image format. The processed image will have an embedded assessment report in its metadata (if supported by the format, e.g., EXIF for JPEG).

If failed: The API returns a JSON object with a HTTP status code indicating failure (e.g., 400, 422). The JSON body includes a reason for failure and the internal assessment data that led to the failure.

Example Failure Response (JSON):

JSON

1
2
3
4
5
6
7
8
9
{
  "reason": "failed because of low sharpness and eyes not fully open",
  "assessment": {
    "UnifiedQualityScore": 45.0,
    "Sharpness": 30.0,
    "EyesOpen": 50.0,
    // ... other assessment fields
  }
}