Vision API: Face Match

This guide explains how to compare two face images using OpenAtman Vision APIs. Start with the basic endpoint, then move to advanced controls when needed.

Quick Overview

Upload two images: image1 and image2.
Set threshold_percent to control strictness of matching.
Use /advanced endpoint for face selection and tuning options.

1. Basic Face Match API

Use this endpoint for default matching behavior. It is the easiest way to get started.

curl --location 'http://127.0.0.1:8091/API/v1.0/face/match/upload' \
--header 'x-api-key: YOUR_OPENATMAN_VISION_API_KEY' \
--form 'image1=@"/path/to/image1.jpg"' \
--form 'image2=@"/path/to/image2.jpg"' \
--form 'threshold_percent="75"'

2. Advanced Face Match API

Use the advanced endpoint when you need more control over face selection, detection confidence, or matching behavior.

curl --location 'http://api.vision.openatman.com/API/v1.0/face/match/upload/advanced' \
--header 'x-api-key: YOUR_OPENATMAN_VISION_API_KEY' \
--form 'image1=@"/path/to/image1.jpg"' \
--form 'image2=@"/path/to/image2.jpg"' \
--form 'threshold_percent="70"' \
--form 'image1_face_index="-1"' \
--form 'image2_face_index="-1"' \
--form 'accuracy_mode="fast"' \
--form 'use_heuristic_fallback="false"' \
--form 'min_det_score="0.40"' \
--form 'auto_pair_best="true"'

Parameter Guide (Simple)

threshold_percent: Match confidence cutoff (example: 70 or 75).

image1_face_index / image2_face_index: Face index to compare. Use -1 for auto-selection.

accuracy_mode: Allowed values are fast and balance.

use_heuristic_fallback: Enables fallback logic when detection is challenging.

min_det_score: Minimum detection confidence accepted for face extraction.

auto_pair_best: Automatically pairs the best candidate faces when multiple faces exist.

Recommended Usage

Start with accuracy_mode=balance for stable quality. Usefast when lower latency is more important than maximum matching accuracy.