Face Detection API Reference - Magic Hour Docs

Detect faces in an image or video.

Use this API to get the list of faces detected in the image or video to use in the face swap photo or face swap video API calls for multi-face swaps.

Note: Face detection is free to use for the near future. Pricing may change in the future.

POST /v1/face-detection

Python

Python

from magic_hour import Client
from os import getenv

client = Client(token=getenv("API_TOKEN"))
res = client.v1.face_detection.generate(
    assets={"target_file_path": "/path/to/1234.png"}, confidence_score=0.5
    wait_for_completion=True,
    download_outputs=True,
    download_directory="."
)

200

{
  "id": "uuid-example",
  "credits_charged": 123
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <api_key>, where <api_key> is your API key. To get your API key, go to Developer Hub and click "Create new API Key".

Body

application/json

Body

assets · object · required

Provide the assets for face detection

Show child attributes

confidence_score · number · default: 0.5

Confidence threshold for filtering detected faces.

• Higher values (e.g., 0.9) include only faces detected with high certainty, reducing false positives.
• Lower values (e.g., 0.3) include more faces, but may increase the chance of incorrect detections.

Required range: 0 <= x <= 1Must be a multiple of 0.05

Example:

0.5

Response

200

application/json

200

id · string · required

The id of the task. Use this value in the get face detection details API to get the details of the face detection task.

Example:

"uuid-example"

credits_charged · integer · required

The credits charged for the task.