Verify whether two images match

curl --request POST \
  --url https://api.deepface.dev/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "img1": "<string>",
  "img2": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({img1: '<string>', img2: '<string>'})
};

fetch('https://api.deepface.dev/verify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.deepface.dev/verify"

payload = {
    "img1": "<string>",
    "img2": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "verified": true,
  "distance": 123,
  "threshold": 123,
  "model": "<string>",
  "facial_areas": {},
  "time": 123
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

POST

verify

Verify whether two images match

curl --request POST \
  --url https://api.deepface.dev/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "img1": "<string>",
  "img2": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({img1: '<string>', img2: '<string>'})
};

fetch('https://api.deepface.dev/verify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.deepface.dev/verify"

payload = {
    "img1": "<string>",
    "img2": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "verified": true,
  "distance": 123,
  "threshold": 123,
  "model": "<string>",
  "facial_areas": {},
  "time": 123
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

Authorizations

Authorization

string

header

required

Use your API key as a bearer token.

Headers

x-request-id

string<uuid>

Optional UUID used for request tracing. Use a new UUID for each logical request and preserve the echoed value when contacting support. The gateway forwards the normalized or generated UUID on every internal admission retry. The coordinated gateway release extends UUID replay protection to prepaid/free calls. Reusing a postpaid UUID returns 409 request_id_conflict rather than replaying a cached result; do not change IDs to bypass an uncertain outcome.

X-Request-Priority

number<double> | null

Optional global group and own-account queue priority, across its API keys, on each gateway process. Every finite positive value goes ahead of that account's normal queued requests; lower positive values run first with FIFO ties. There is no upper bound of 1: 1, 10 and 100 all request priority. Omitted, null and zero use normal own-account queue order and no per-request priority surcharge. Zero is handled normally without rejecting the request. Accepts JSON number spelling in decimal or scientific notation; negative, blank, repeated, comma-separated, nonfinite and overflow/underflow values return 400 invalid_priority before billing reservation or inference. Double precision can round close numbers equal. Global eligible calls run in strict order: enterprise with positive priority, non-enterprise with positive priority, enterprise normal, non-enterprise normal. Within a group, numeric values only reorder the caller's own account; other accounts retain their positions. No aging or 4:1 rotation overrides groups. It never preempts running work, reorders model-server work, reserves capacity, bypasses limits or guarantees latency. A full queue can still reject a priority request. REST priority is header-only; MCP accepts the equivalent optional priority argument. Experimental async compare rejects positive priority headers with 400 unsupported_priority; null and zero are accepted normally. Completed calls with any explicitly positive own-queue priority cost twice the standard rate, even when idle. Under the default contract policy an enterprise lane also costs 2x, once. Negotiated request-only contracts include enterprise access at the standard rate. Completed no-face results are billable; failures are free.

Required range: x >= 0

x-deepface-billing-profile

string

An explicitly negotiated integration tariff assertion, not an API key. Ordinary clients should omit this header. An integration that requires a profile must send its exact configured identifier and dedicated API key; an absent or mismatched assertion returns 409 billing_profile_mismatch before compute. Profile-specific request restrictions are checked by the gateway and violations return 400 billing_tariff_scope_rejected. This header cannot enable a tariff, change the account's rates, or grant access.

Body

img1

string

required

Base64 image payload, data URL, or, when remote URL input is enabled on the model server, a public HTTPS image URL from any domain. The managed API requires a direct, non-redirecting JPEG, PNG, or WebP response from a publicly routable destination. It rejects images that exceed the active byte, request-size, decoded pixel, or download timeout limits before forwarding work to the model runtime.

img2

string

required

model_name

string

Approved model name from the current allowlist. For /verify and /represent, omitted, blank, or overlong values are treated as absent and the gateway injects the active default model.

Maximum string length: 200

Example:

"Facenet"

detector_backend

string

Optional detector backend from the current allowlist. When the active detector misses a face, the service may retry configured fallback detectors before returning no_face_detected.

Example:

"opencv"

enforce_detection

boolean

default:true

align

boolean

default:true

normalization

string

Optional DeepFace normalization mode.

distance_metric

enum<string>

Available options:

cosine,

euclidean,

euclidean_l2

Example:

"cosine"

Response

Verification result

verified

boolean

required

distance

number

required

threshold

number

required

model

string

facial_areas

object

Show child attributes

time

number

Getting started

Runnable examples

Guides

API reference

Verify whether two images match

Authorizations

Headers

Body

Response