Compare two faces

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

Content type multipart/form-data

Compares the faces in two images and tells you whether they're the same person, with a similarity score. The call is synchronous: you get back the finished run, already charged.

Request

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

Response

{8 items"id":"b2a7f0de-5c41-4d2b-8d90-1f6e3c..."
"tool_url_path":"face-match-1-1"
"status":"completed"
"params":{1 item"threshold":70
}
"result":{4 items"results":[1 item0:{11 items"filename":"candidate.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":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 item0:{2 items"code":"blurry"
"message":"blurry (sharpness 15/100)"
}
]
}
}
]
"matched_count":1
"advanced_analysis":{5 items"available":true
"summary":"The two photos were found to s..."
"summary_format":"markdown"
"human_review":{2 items"required":true
"reason":"the candidate photo is blurry"
}
"error":null
}
"human_review":{2 items"required":true
"reasons":[2 items0:"Low-quality target photo: blur..."
1:"AI analysis: the candidate pho..."
]
}
}
"error":null
"credits":5
"created_at":"2026-09-18T09:12:04.182741Z"
}

Authentication

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

Request

Body

Name	Type	Required	Description
`file1`	file	Required	The reference image. PNG or JPEG, up to 2 MB.
`file2`	file	Required	The image to compare against it. PNG or JPEG, up to 2 MB.
`threshold`	number	Optional	Similarity percentage, 0-100, above which a face counts as a match. Default `70.0`
`advanced_analysis`	boolean	Optional	Advanced analysis and AI summary: adds `result.advanced_analysis`, a plain-language summary report of the comparison 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.

Field	Type	Description
`result.matched_count`	integer	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[].filename`	string	Which image this entry is for.
`result.results[].error`	string \| null	Why this image couldn't be compared — no face found, too blurry. Every other image still returns its own verdict.
`result.results[].is_match`	boolean \| null	Whether this image is the same person. Null means no verdict (see `error`), which is not the same as false.
`result.results[].similarity`	number \| 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_confidence`	number \| 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_confidence`	number \| null	The same, for this compared image.
`result.results[].source_bounding_box`	object \| 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_box`	object \| null	The same, for this compared image.
`result.results[].target_quality`	object \| 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.reference`	object \| 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.target`	object \| null	The same, for the compared image.
`result.results[].face_details.*.confidence`	number	How sure detection is that this is a face, 0-100.
`result.results[].face_details.*.age_range`	object \| null	Estimated age range, `low` and `high` in years.
`result.results[].face_details.*.gender`	object \| 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_occluded`	object \| 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.*.sunglasses`	object \| null	Whether sunglasses are worn, with `confidence`.
`result.results[].face_details.*.eyeglasses`	object \| null	Whether ordinary glasses are worn, with `confidence`. Not a quality problem on its own.
`result.results[].face_details.*.eyes_open`	object \| null	Whether both eyes are open, with `confidence`.
`result.results[].face_details.*.beard`	object \| null	Whether there is a beard, with `confidence`.
`result.results[].face_details.*.mustache`	object \| null	Whether there is a mustache, with `confidence`.
`result.results[].face_details.*.quality`	object \| null	`brightness` and `sharpness` of the face, 0-100 each.
`result.results[].face_details.*.pose`	object \| null	Head angle in degrees: `yaw` (turned left/right), `pitch` (tilted up/down), `roll`.
`result.results[].face_details.*.face_size_percent`	number \| 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[].code`	string	Stable — branch on this: `blurry`, `dark`, `overexposed`, `head_turned`, `head_tilted`, `face_too_small`, `eyes_closed`, `occluded`, `sunglasses`.
`result.results[].quality_warnings.target[].message`	string	The problem in words, with its figure — e.g. `blurry (sharpness 12/100)`. For display; its wording may change.
`result.human_review.required`	boolean	Whether a person should confirm this result before you rely on it. Always present. True when a photo has a quality warning, the score is within 5 of your threshold, there is no verdict, or the AI analysis recommends it.
`result.human_review.reasons[]`	string[]	Why, one entry per reason, e.g. `Low-quality target photo: blurry (sharpness 15/100)`. Empty when `required` is false. For display; branch on `required`.
`result.advanced_analysis`	object	Present only when you sent `advanced_analysis=true`.
`result.advanced_analysis.human_review`	object \| null	The AI's own call — `required` and a short `reason`. It can add to `result.human_review` but never clear it, so branch on `result.human_review.required`.
`result.advanced_analysis.summary`	string \| null	A plain-language read of the result, written from the score, the face details and the quality warnings. Points a reviewer should act on are in bold. It never overrides `is_match`.
`result.advanced_analysis.available`	boolean	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_format`	string	`markdown` — render `summary` as Markdown (paragraphs, bold, italics, lists).
`result.advanced_analysis.error`	string \| null	Why the summary couldn't be written, when `available` is false.

Errors

Status	Code	When
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.