Detect Faces - Akool open api documents

This is the main endpoint for face detection. It automatically detects whether the input is an image or video and processes accordingly.

Key Features

Auto Media Type Detection: Automatically determines if the input is an image or video
6-Point Landmarks: Detects 6 key facial landmarks for each face
Bounding Boxes: Provides precise face region coordinates
Video Face Tracking: Tracks faces across frames and identifies removed faces
Async Processing: Downloads and processes media asynchronously for better performance

How It Works

Media Type Detection: The API analyzes the URL to determine if it’s an image or video
Media Download: Downloads the media from the provided URL asynchronously
Processing:
- For images: Loads and analyzes the single image
- For videos: Extracts frames at regular intervals and analyzes each frame
Face Detection: Uses InsightFace model to detect faces and landmarks
Face Tracking (videos only): Tracks faces across frames and marks previous positions as removed

Request Parameters

url (required)

The URL of the media file to process. Must be publicly accessible. Supported formats:

Images: .jpg, .jpeg, .png, .bmp, .webp
Videos: .mp4, .mov, .avi, .webm

num_frames (optional)

Number of frames to extract and analyze from videos. Default: 5

For Images: This parameter is NOT required and will be ignored.
For Videos: This parameter is recommended to control the number of frames analyzed.

Recommendations for videos:

Short videos (< 10s): 5-10 frames
Medium videos (10-30s): 10-20 frames
Long videos (> 30s): 20-50 frames

Response Format

Success Response

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [
        [[294, 65], [316, 64], [304, 76], [305, 86], [296, 86], [314, 85]]
      ],
      "landmarks_str": [
        "294,65:316,64:304,76:305,86:296,86:314,85"
      ],
      "region": [[284, 38, 43, 63]],
      "removed": [],
      "frame_time": null
    }
  }
}

Response Fields

error_code

Type: integer
0: Success
1: Error occurred (check error_msg)

error_msg

Type: string
Success: "SUCCESS"
Error: Detailed error message

faces_obj

Type: object
Dictionary keyed by frame index (as string)
For images: Only "0" key is present
For videos: Multiple keys like "0", "5", "10", etc.

Each frame object contains:

landmarks

Type: array
Array of 6-point landmarks for each detected face
Format: [[[x1, y1], [x2, y2], [x3, y3], [x4, y4], [x5, y5], [x6, y6]], ...]
Order: Left Eye, Right Eye, Nose, Mouth Center, Left Mouth Corner, Right Mouth Corner
Note: The Mouth Center (4th point) is calculated as the midpoint of the X-axis between the mouth corners, while the Y-axis remains unchanged (aligned with the corners).

landmarks_str

Type: array
String representation of the landmarks
Format: ["x1,y1:x2,y2:x3,y3:x4,y4:x5,y5:x6,y6"]
For Face Swap API: When using this for the opts parameter in Face Swap, only use the first 4 coordinate pairs (Left Eye, Right Eye, Nose, Mouth Center). Truncate the string after the 4th point (e.g., x1,y1:x2,y2:x3,y3:x4,y4).

region

Type: array
Bounding boxes for each detected face
Format: [[x, y, width, height], ...]
(x, y) is the top-left corner of the bounding box

removed

Type: array
Bounding boxes of faces that were present in previous frames but are no longer visible
Only applicable for video processing
Format: [[x, y, width, height], ...]

frame_time

Type: number or null
Time in seconds for this frame in the video
null for images

Examples

Example 1: Image Face Detection

Request:

{
  "url": "https://example.com/portrait.jpg"
}

For image detection, the num_frames parameter is not required and will be ignored if provided.

Response:

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [
        [[320, 240], [420, 240], [370, 300], [370, 350], [340, 350], [400, 350]],
        [[650, 220], [720, 220], [685, 270], [685, 310], [660, 310], [710, 310]]
      ],
      "landmarks_str": [
        "320,240:420,240:370,300:370,350:340,350:400,350",
        "650,220:720,220:685,270:685,310:660,310:710,310"
      ],
      "region": [
        [300, 200, 150, 180],
        [630, 180, 120, 160]
      ],
      "removed": [],
      "frame_time": null
    }
  }
}

Example 2: Video Face Detection

Request:

{
  "url": "https://example.com/video.mp4",
  "num_frames": 10
}

Response:

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [
        [[320, 240], [420, 240], [370, 300], [370, 350], [340, 350], [400, 350]]
      ],
      "landmarks_str": [
        "320,240:420,240:370,300:370,350:340,350:400,350"
      ],
      "region": [[300, 200, 150, 180]],
      "removed": [],
      "frame_time": 0.0
    },
    "10": {
      "landmarks": [
        [[325, 245], [425, 245], [375, 305], [375, 355], [345, 355], [405, 355]]
      ],
      "landmarks_str": [
        "325,245:425,245:375,305:375,355:345,355:405,355"
      ],
      "region": [[305, 205, 150, 180]],
      "removed": [[300, 200, 150, 180]],
      "frame_time": 0.333
    }
  }
}

Error Responses

Invalid URL

{
  "error_code": 1,
  "error_msg": "Invalid URL format",
  "faces_obj": {}
}

No Faces Detected

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [],
      "landmarks_str": [],
      "region": [],
      "removed": [],
      "frame_time": null
    }
  }
}

Processing Error

{
  "error_code": 1,
  "error_msg": "Failed to download media from URL",
  "faces_obj": {}
}

Use Cases

1. Face Swap Preprocessing

Detect face landmarks to prepare images for face swapping operations.

Note: When using the landmarks for the Face Swap API (opts parameter), extract only the first 4 groups of coordinates from landmarks_str (Left Eye, Right Eye, Nose, Mouth Center).

2. Face Recognition

Extract face regions and landmarks for face recognition systems.

3. Video Analysis

Track faces across video frames for content analysis or editing.

4. Face Alignment

Use landmarks to align faces for consistent processing.

5. Facial Animation

Use landmarks as control points for facial animation.

Best Practices

URL Requirements

Use HTTPS URLs for better security
Ensure URLs are publicly accessible (no authentication required)
Use direct links to media files (avoid redirects)

Performance Optimization

For videos, use an appropriate num_frames value
- More frames = higher accuracy but longer processing time
- Fewer frames = faster processing but may miss faces
Cache results if processing the same media multiple times

Error Handling

Always check the error_code before processing results:

if response["error_code"] != 0:
    print(f"Error: {response['error_msg']}")
    return

faces = response["faces_obj"]
# Process faces...

Rate Limits

Rate limits apply to this endpoint. Excessive requests may be throttled. Please implement appropriate retry logic with exponential backoff.

Authorizations

x-api-key

string

header

required

Your API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded.

Body

application/json

url

string<uri>

required

URL of the video or image to process. The media type will be auto-detected based on the file extension.

Example:

"https://example.com/media.mp4"

num_frames

integer

default:5

Number of frames to extract and analyze (only used for videos, ignored for images)

Required range: 1 <= x <= 100

Example:

5

Response

Face detection completed successfully

error_code

integer

required

Error code (0: success, 1: error)

Example:

0

error_msg

string

required

Error message or success message

Example:

"SUCCESS"

faces_obj

object

required

Dictionary of face detection results keyed by frame index (as string). For images, only frame "0" will be present. For videos, multiple frames will be present (e.g., "0", "5", "10", etc.)

Show child attributes

Example:

{
  "0": {
    "landmarks": [
      [
        [294, 65],
        [316, 64],
        [304, 76],
        [305, 86],
        [296, 86],
        [314, 85]
      ]
    ],
    "landmarks_str": ["294,65:316,64:304,76:305,86:296,86:314,85"],
    "region": [[284, 38, 43, 63]],
    "removed": [],
    "frame_time": null
  }
}

Authentication

Face Swap

Streaming Avatar

Talking Photo

Video Translation

Face Detection

AI Tools Suite

​Key Features

​How It Works

​Request Parameters

​url (required)

​num_frames (optional)

​Response Format

​Success Response

​Response Fields

​error_code

​error_msg

​faces_obj

landmarks

landmarks_str

region

removed

frame_time

​Examples

​Example 1: Image Face Detection

​Example 2: Video Face Detection

​Error Responses

​Invalid URL

​No Faces Detected

​Processing Error

​Use Cases

​1. Face Swap Preprocessing

​2. Face Recognition

​3. Video Analysis

​4. Face Alignment

​5. Facial Animation

​Best Practices

​URL Requirements

​Performance Optimization

​Error Handling

​Rate Limits

Authorizations

Body

Response

Key Features

How It Works

Request Parameters

url (required)

num_frames (optional)

Response Format

Success Response

Response Fields

error_code

error_msg

faces_obj

Examples

Example 1: Image Face Detection

Example 2: Video Face Detection

Error Responses

Invalid URL

No Faces Detected

Processing Error

Use Cases

1. Face Swap Preprocessing

2. Face Recognition

3. Video Analysis

4. Face Alignment

5. Facial Animation

Best Practices

URL Requirements

Performance Optimization

Error Handling

Rate Limits