canonical: https://jentic.com/apis/hirak.site/hirak-faceapi

# Hirak Site Hirak FaceAPI

Jentic publishes the only available OpenAPI specification for Hirak FaceAPI, keeping it validated and agent-ready. Hirak FaceAPI is a RapidAPI-distributed face analysis service offering five POST endpoints that detect faces, locate landmarks, compare two faces, analyse facial attributes such as age, gender, and emotion, and produce face encodings suitable for downstream matching. It is authenticated with the X-RapidAPI-Key header and aimed at developers who need lightweight face features without the complexity of cloud-vendor vision SDKs. Image input is supplied as part of each POST request.

## For AI agents

Detect faces, find facial landmarks, compare faces, analyse age, gender, and emotion, and generate face encodings via five POST endpoints. Authenticated with an X-RapidAPI-Key header.

## Scope

Does not handle full identity verification, document parsing, or biometric template storage - use for face detection, comparison, and attribute analysis only.

## Capabilities

- Detect faces in an image and return bounding boxes from POST /detect
- Locate facial landmarks such as eyes, nose, and mouth using POST /landmarks
- Compare two faces for similarity to support verification flows via POST /compare
- Analyse facial attributes including age, gender, and emotion through POST /analyze
- Generate a face encoding vector for downstream matching with POST /encode
- Run lightweight identity-verification or moderation pipelines without a cloud vendor SDK

## Use cases

### Lightweight Identity Verification

Onboarding flows that need a 'selfie matches ID photo' check use POST /compare to receive a similarity score. The result lets an agent route the user to a manual review queue or auto-approve based on a threshold, without the integration weight of a full KYC vendor.

Example prompt: Given a selfie image and an ID photo, call POST /compare and route to manual review if the similarity score is below 0.85.

### Photo Tagging in a Media Library

A media library tags photos with faces and emotions for search and discovery. Hirak FaceAPI's /detect, /landmarks, and /analyze endpoints return the structured data needed to populate per-photo metadata so users can filter by 'photos with smiling people'.

Example prompt: For each new uploaded photo, call POST /detect and POST /analyze, then store the bounding boxes and dominant emotion as photo metadata.

### Content Moderation Pre-Filter

Moderation pipelines use face presence as a signal before sending content to a human reviewer. /detect quickly identifies whether an image contains a face, and /analyze can flag minors based on age estimates, letting the platform prioritise the review queue without scaling a full moderation team.

Example prompt: When an image is uploaded to the platform, call POST /analyze and queue any image where the estimated age is below 18 for human review.

### AI Agent Face Matching Tool

An AI agent matches a candidate photo against a known set of encodings. Through Jentic, the agent searches for the encode operation, loads the schema, and executes POST /encode for each image, then performs vector comparison locally. The X-RapidAPI-Key stays in your Jentic One instance.

Example prompt: For a new photo, search Jentic for 'generate face encoding', execute POST /encode, and compare the returned vector against the stored encodings to find the closest match.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/detect` | Detect faces in an image |
| POST | `/landmarks` | Locate facial landmarks |
| POST | `/compare` | Compare two faces for similarity |
| POST | `/analyze` | Analyse age, gender, and emotion |
| POST | `/encode` | Generate a face encoding vector |

## Key resources

- **Detection** — Face detection and landmark location.
- **Comparison** — Pairwise face similarity scoring.
- **Analysis** — Age, gender, and emotion estimation.
- **Encoding** — Face encoding vectors for downstream matching.

## Why Jentic

- **Setup:** Wiring the Hirak FaceAPI by hand means sending an X-RapidAPI-Key on every call and posting image data to the right face endpoint for each task. Through Jentic you install once, import the Hirak FaceAPI from the API Directory, store the RapidAPI key once, and your agent calls it.
- **Permission scoping:** The Hirak FaceAPI takes image input in the request body rather than exposing scopable resource ids, so scoping stays at the operation level: limit the agent to the operations it needs, such as detecting a face or comparing two faces. You choose that set, so operations like landmark extraction or encoding are only available if you include them.
- **Credential handling:** Your X-RapidAPI-Key is stored once, encrypted, by your own Jentic One instance and injected as a header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'compare two faces', and Jentic returns the matching POST /compare or /detect operation with its body schema so the agent picks the right endpoint without reading the reference docs.

## Related APIs

- **FaceCheck.ID API** — Reverse face search service for matching a photo against a public web index.
- **OpenAI API** — GPT-4 vision can describe faces in natural language to complement Hirak's structured outputs.
- **Mindee API** — Document understanding API for ID parsing alongside Hirak's face matching.

## FAQ

### Why is there no official OpenAPI spec for Hirak FaceAPI?

Hirak does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Hirak FaceAPI via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Hirak FaceAPI use?

Hirak FaceAPI is distributed via RapidAPI and authenticated with the X-RapidAPI-Key header. Through Jentic, the key is held in your Jentic One instance and injected at execution time so the raw RapidAPI key never enters the agent context.

### Can I compare two faces for similarity?

Yes. POST /compare accepts two images and returns a similarity score that can be thresholded to decide if they are the same person. Combine with POST /detect first if you need to confirm both inputs contain a face before comparison.

### What are the rate limits for the Hirak FaceAPI?

RapidAPI plan tiers govern throughput; the OpenAPI spec does not declare specific limits. Check your RapidAPI subscription for monthly quotas and queue large image-batch jobs to stay within plan limits.

### How do I run face detection through Jentic?

Run pip install jentic, then await client.search('detect faces in an image'), load the POST /detect schema, and execute with the image payload. The response contains bounding boxes for any faces found.

### Does Hirak FaceAPI store the face encodings I generate?

No. POST /encode returns a vector to the caller; storage is the integrator's responsibility. Persist encodings in your own vector store and call /encode again on each new candidate image to get a comparable vector.

### Can I limit what my agent is allowed to do with the Hirak FaceAPI?

Yes. Because you run Jentic One yourself, your own rules decide which of the five Hirak FaceAPI operations the agent may call. The API takes image data in the request body rather than exposing scopable resource ids, so scoping happens at the operation level: you can allow only POST /detect and POST /compare for a verification flow, for example, and leave POST /landmarks, POST /analyze, and POST /encode unavailable. The agent can call an operation only if you include it in that set, and your X-RapidAPI-Key stays in your own instance and is injected at execution time.