kriyam.aistudioAPI reference
1:N Face Match

Compare one face against many

POSThttps://studioapi.kriyam.ai/models/facex/1-n/v1

Content type multipart/form-data

Compares one reference face against several target images in a single call and tells you which of them match. The call is synchronous: you get back the finished run, already charged.

Request

curl -X POST "https://studioapi.kriyam.ai/models/facex/1-n/v1" \
  -H "X-API-Key: $KRIYAM_API_KEY" \
  -F "reference=@reference.jpg" \
  -F "targets=@candidate-1.jpg" \
  -F "threshold=70.0" \
  -F "advanced_analysis=True"

Response

{8 items
"id":"b2a7f0de-5c41-4d2b-8d90-1f6e3c..."
"tool_url_path":"face-match-1-n"
"status":"completed"
"params":{1 item
"threshold":70
}
"result":{4 items
"results":[2 items
0:{12 items
"filename":"candidate-1.jpg"
"error":null
"similarity":98.6
"is_match":true
"source_face_confidence":99.98
"source_bounding_box":{4 items
"left":0.31
"top":0.18
"width":0.36
"height":0.47
}
"target_face_confidence":99.94
"target_bounding_box":{4 items
"left":0.28
"top":0.21
"width":0.39
"height":0.51
}
"target_quality":{2 items
"brightness":82.4
"sharpness":46.9
}
"face_details":{2 items
"reference":{12 items
"confidence":99.98
"age_range":{2 items
"low":27
"high":33
}
"gender":{2 items
"value":"Male"
"confidence":99.6
}
"face_occluded":{2 items
"value":false
"confidence":98.1
}
"sunglasses":{2 items
"value":false
"confidence":99.9
}
"eyeglasses":{2 items
"value":false
"confidence":97.4
}
"eyes_open":{2 items
"value":true
"confidence":98.7
}
"beard":{2 items
"value":false
"confidence":92.3
}
"mustache":{2 items
"value":true
"confidence":88
}
"quality":{2 items
"brightness":78.2
"sharpness":86.3
}
"pose":{3 items
"yaw":-2.4
"pitch":3.1
"roll":-1.2
}
"face_size_percent":17.4
}
"target":{12 items
"confidence":99.98
"age_range":{2 items
"low":25
"high":31
}
"gender":{2 items
"value":"Male"
"confidence":99.6
}
"face_occluded":{2 items
"value":false
"confidence":98.1
}
"sunglasses":{2 items
"value":false
"confidence":99.9
}
"eyeglasses":{2 items
"value":false
"confidence":97.4
}
"eyes_open":{2 items
"value":true
"confidence":98.7
}
"beard":{2 items
"value":false
"confidence":92.3
}
"mustache":{2 items
"value":true
"confidence":88
}
"quality":{2 items
"brightness":78.2
"sharpness":81
}
"pose":{3 items
"yaw":8.7
"pitch":3.1
"roll":-1.2
}
"face_size_percent":17.4
}
}
"quality_warnings":{2 items
"reference":[]0 items
"target":[]0 items
}
"human_review":{2 items
"required":false
"reasons":[]0 items
}
}
1:{12 items
"filename":"candidate-2.jpg"
"error":null
"similarity":41.2
"is_match":false
"source_face_confidence":99.98
"source_bounding_box":{4 items
"left":0.31
"top":0.18
"width":0.36
"height":0.47
}
"target_face_confidence":99.94
"target_bounding_box":{4 items
"left":0.28
"top":0.21
"width":0.39
"height":0.51
}
"target_quality":{2 items
"brightness":82.4
"sharpness":46.9
}
"face_details":{2 items
"reference":{12 items
"confidence":99.98
"age_range":{2 items
"low":27
"high":33
}
"gender":{2 items
"value":"Male"
"confidence":99.6
}
"face_occluded":{2 items
"value":false
"confidence":98.1
}
"sunglasses":{2 items
"value":false
"confidence":99.9
}
"eyeglasses":{2 items
"value":false
"confidence":97.4
}
"eyes_open":{2 items
"value":true
"confidence":98.7
}
"beard":{2 items
"value":false
"confidence":92.3
}
"mustache":{2 items
"value":true
"confidence":88
}
"quality":{2 items
"brightness":78.2
"sharpness":86.3
}
"pose":{3 items
"yaw":-2.4
"pitch":3.1
"roll":-1.2
}
"face_size_percent":17.4
}
"target":{12 items
"confidence":99.98
"age_range":{2 items
"low":25
"high":31
}
"gender":{2 items
"value":"Male"
"confidence":99.6
}
"face_occluded":{2 items
"value":false
"confidence":98.1
}
"sunglasses":{2 items
"value":false
"confidence":99.9
}
"eyeglasses":{2 items
"value":false
"confidence":97.4
}
"eyes_open":{2 items
"value":true
"confidence":98.7
}
"beard":{2 items
"value":false
"confidence":92.3
}
"mustache":{2 items
"value":true
"confidence":88
}
"quality":{2 items
"brightness":78.2
"sharpness":14.9
}
"pose":{3 items
"yaw":8.7
"pitch":3.1
"roll":-1.2
}
"face_size_percent":17.4
}
}
"quality_warnings":{2 items
"reference":[]0 items
"target":[1 item
0:{2 items
"code":"blurry"
"message":"blurry (sharpness 15/100)"
}
]
}
"human_review":{2 items
"required":true
"reasons":[2 items
0:"Low-quality target photo: blur..."
1:"AI analysis: the photo is blur..."
]
}
}
]
"matched_count":1
"advanced_analysis":{5 items
"available":true
"summary":"candidate-1.jpg was found to s..."
"summary_format":"markdown"
"human_review":{2 items
"candidate-1.jpg":{2 items
"required":false
"reason":null
}
"candidate-2.jpg":{2 items
"required":true
"reason":"the photo is blurry"
}
}
"error":null
}
"human_review":{2 items
"required":true
"reasons":[2 items
0:"candidate-2.jpg: Low-quality t..."
1:"candidate-2.jpg: AI analysis: ..."
]
}
}
"error":null
"credits":7
"created_at":"2026-09-18T09:12:04.182741Z"
}

Authentication

Send your key in the X-API-Key header. See Authentication.

Request

Body

NameTypeRequiredDescription
referencefileRequired

The face to search for. PNG or JPEG, up to 2 MB.

targetsfile[]Required

The images to compare against it — repeat the field once per image, up to 5.

thresholdnumberOptional

Similarity percentage, 0-100, above which a target counts as a match.

Default 70.0

advanced_analysisbooleanOptional

Advanced analysis and AI summary: adds result.advanced_analysis, a plain-language summary report of the whole search written in Markdown from the scores, the face details and the quality warnings, with its own human-review call. Charged as an extra on top of the comparison.

Default false

Response

200 OK

Returns the run envelope. The fields below are what this tool puts inside it.

FieldTypeDescription
result.matched_countinteger

How many compared images matched the reference at the threshold you sent.

result.results[]object[]

One entry per compared image, in the order you sent them.

result.results[].filenamestring

Which image this entry is for.

result.results[].errorstring | null

Why this image couldn't be compared — no face found, too blurry. Every other image still returns its own verdict.

result.results[].is_matchboolean | null

Whether this image is the same person. Null means no verdict (see error), which is not the same as false.

result.results[].similaritynumber | null

How alike the two faces are, 0-100 — reported whether or not it clears your threshold. Null only when no face could be scored or the comparison errored.

result.results[].source_face_confidencenumber | null

How sure the detector is that it found a face in the reference image, 0-100. About detection, not about the match.

result.results[].target_face_confidencenumber | null

The same, for this compared image.

result.results[].source_bounding_boxobject | null

Where the face sits in the reference image — left, top, width, height as fractions of the image, so they survive resizing.

result.results[].target_bounding_boxobject | null

The same, for this compared image.

result.results[].target_qualityobject | null

brightness and sharpness, 0-100, for the compared face. Low values explain a weak score. Only ever reported for the compared face, never the reference.

result.results[].face_details.referenceobject | null

What face detection read from the reference photo's face. Null if it couldn't read one — the comparison itself is unaffected.

result.results[].face_details.targetobject | null

The same, for the compared image.

result.results[].face_details.*.confidencenumber

How sure detection is that this is a face, 0-100.

result.results[].face_details.*.age_rangeobject | null

Estimated age range, low and high in years.

result.results[].face_details.*.genderobject | null

value (Male or Female) and confidence. A binary prediction from appearance, not a person's gender identity — never use it to decide anything about the person.

result.results[].face_details.*.face_occludedobject | null

value true when the eyes, nose or mouth are cut off or covered (a mask, dark sunglasses, a hand, a phone), with confidence. Ordinary glasses and hair don't count.

result.results[].face_details.*.sunglassesobject | null

Whether sunglasses are worn, with confidence.

result.results[].face_details.*.eyeglassesobject | null

Whether ordinary glasses are worn, with confidence. Not a quality problem on its own.

result.results[].face_details.*.eyes_openobject | null

Whether both eyes are open, with confidence.

result.results[].face_details.*.beardobject | null

Whether there is a beard, with confidence.

result.results[].face_details.*.mustacheobject | null

Whether there is a mustache, with confidence.

result.results[].face_details.*.qualityobject | null

brightness and sharpness of the face, 0-100 each.

result.results[].face_details.*.poseobject | null

Head angle in degrees: yaw (turned left/right), pitch (tilted up/down), roll.

result.results[].face_details.*.face_size_percentnumber | null

How much of the photo the face's box covers, as a percentage. Larger faces compare more reliably.

result.results[].quality_warnings.reference[]object[]

Problems with the reference photo that make the score less certain. Empty when there are none. Warnings never change similarity or is_match.

result.results[].quality_warnings.target[]object[]

The same, for the compared image.

result.results[].quality_warnings.target[].codestring

Stable — branch on this: blurry, dark, overexposed, head_turned, head_tilted, face_too_small, eyes_closed, occluded, sunglasses.

result.results[].quality_warnings.target[].messagestring

The problem in words, with its figure — e.g. blurry (sharpness 12/100). For display; its wording may change.

result.results[].human_review.requiredboolean

Whether a person should confirm this target's result before you rely on it. True when its photo or the reference has a quality warning, its score is within 5 of your threshold, it has no verdict, or the AI analysis recommends it for this target.

result.results[].human_review.reasons[]string[]

Why, for this target. Empty when required is false.

result.human_review.requiredboolean

True when any target's human_review.required is.

result.human_review.reasons[]string[]

Every target's reasons, each prefixed with that target's filename.

result.advanced_analysisobject

Present only when you sent advanced_analysis=true.

result.advanced_analysis.summarystring | null

A plain-language read of the whole search, written from every score, face reading and quality warning. Points a reviewer should act on are in bold. It never overrides any target's is_match.

result.advanced_analysis.human_reviewobject

The AI's own call per target, keyed by filename — required and a short reason. It can add to a target's human_review but never clear it.

result.advanced_analysis.availableboolean

Whether the AI summary was written. False means it couldn't be — see error; the comparison above is still complete and correct.

result.advanced_analysis.summary_formatstring

markdown — render summary as Markdown (paragraphs, bold, italics, lists).

result.advanced_analysis.errorstring | null

Why the summary couldn't be written, when available is false.

Errors

StatusCodeWhen
400—

More than 5 target images were sent.

400—

An image is empty, over 2 MB, or can't be decoded. The message names which.

Every keyed call can also get401402403404429— see Errors.