Face Detection API Overview

​

API Endpoints

​

Face Detection Operations

• Detect Faces - Unified endpoint for face detection in images and videos (auto-detects media type)
• Analyze Frames - Multi-frame face analysis with person deduplication for face swap preparation

​

Getting Started

​

Basic Workflow

1. For Image Face Detection:
   • Call the Detect Faces API with an image URL or base64-encoded image
   • Only the url or img parameter is required (no need for num_frames)
   • Receive bounding boxes and 6-point landmarks for all detected faces
   • Optionally get cropped face image URLs with return_face_url=true
   • Use the landmark data for downstream tasks (e.g., face swap, face recognition)
2. For Video Face Detection:
   • Call the Detect Faces API with a video URL
   • Specify the num_frames parameter to control how many frames to analyze (default: 5)
   • Get face tracking data across frames with removed face positions

​

Response Code Description

​

Features

​

Dual Input Modes

1. URL Mode: Provide a publicly accessible URL to an image or video
2. Base64 Mode: Provide base64-encoded image data (with or without data URI prefix)

// URL mode
{ "url": "https://example.com/image.jpg" }

// Base64 mode
{ "img": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." }

​

6-Point Facial Landmarks

1. Left Eye - Center point of the left eye
2. Right Eye - Center point of the right eye
3. Nose Tip - Tip of the nose
4. Mouth Center - Center point of the mouth (X-axis midpoint between mouth corners)
5. Left Mouth Corner - Left corner of the mouth
6. Right Mouth Corner - Right corner of the mouth

​

Cropped Face Images

• face_urls: URLs to cropped face images stored in cloud storage
• crop_region: The region coordinates used for cropping
• crop_landmarks: Landmarks relative to the cropped image

​

Single Face Mode

• Portrait photos where you only care about the main subject
• ID photos with a single person
• Reducing response size when multiple faces are detected

​

Face Tracking for Videos

• Persistent Face IDs - Tracks the same face across multiple frames
• Removed Faces - Identifies faces that were present in previous frames but are no longer visible
• Frame Timing - Provides timestamp information for each frame

​

Auto Media Type Detection

• File extension (.jpg, .png, .mp4, .mov, etc.)
• Content-Type header from the URL
• Fallback to content analysis if needed

​

Best Practices

​

Image Requirements

• Quality: Use high-resolution images for better detection accuracy
• Face Visibility: Ensure faces are clearly visible and not obscured
• Lighting: Well-lit images produce better detection results
• Angle: Frontal or slight angle faces work best (±45 degrees)
• Size: Face size should be at least 80x80 pixels

​

Video Requirements

• Duration: Shorter videos process faster
• Frame Rate: Standard frame rates (24-30 fps) are optimal
• Resolution: 720p or higher recommended for best results
• Face Count: API can detect multiple faces per frame
• Encoding: Use standard encoding formats (H.264 recommended)

​

API Usage Tips

• Parameter Usage:
  • For Images: Only url or img parameter is required. The num_frames parameter is NOT needed.
  • For Videos: Both url and num_frames parameters are recommended.
• Frame Selection (for videos only):
  • Short videos (< 10s): 5-10 frames
  • Medium videos (10-30s): 10-20 frames
  • Long videos (> 30s): 20-50 frames
• URL Accessibility: Ensure the media URL is publicly accessible
• Supported Formats:
  • Images: JPG, JPEG, PNG, BMP, WEBP
  • Videos: MP4, MOV, AVI, WEBM

​

Understanding the Response

​

Response Structure

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [
        [[100, 120], [150, 120], [125, 150], [125, 180], [110, 180], [140, 180]]
      ],
      "landmarks_str": [
        "100,120:150,120:125,150:125,180"
      ],
      "region": [[80, 100, 100, 120]],
      "removed": [],
      "frame_time": null,
      "face_urls": null,
      "crop_region": null,
      "crop_landmarks": null
    }
  }
}

​

Field Descriptions

• error_code: Status code (0 = success)
• error_msg: Status message or error description
• faces_obj: Dictionary keyed by frame index (as string)
  • landmarks: Array of 6-point landmarks for each detected face
    • Format: [[x1, y1], [x2, y2], [x3, y3], [x4, y4], [x5, y5], [x6, y6]]
  • landmarks_str: String format of first 4 landmarks for Face Swap API compatibility
    • Format: "x1,y1:x2,y2:x3,y3:x4,y4"
  • region: Bounding boxes for each detected face
    • Format: [x, y, width, height] where (x, y) is the top-left corner
  • removed: Bounding boxes of faces no longer visible (video only)
  • frame_time: Timestamp in seconds for this frame (video only, null for images)
  • face_urls: Cropped face image URLs (only when return_face_url=true)
  • crop_region: Cropping region in original image (only when return_face_url=true)
  • crop_landmarks: Landmarks relative to cropped image (only when return_face_url=true)

​

Common Use Cases

​

Face Detection for Image Processing

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

​

Get Cropped Face Images for Face Swap

{
  "url": "https://example.com/photo.jpg",
  "return_face_url": true
}

​

Face Tracking in Video Content

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

​

Single Face Detection

{
  "url": "https://example.com/group_photo.jpg",
  "single_face": true
}

​

Multiple Face Detection

​

Integration with Face Swap

1. Use Face Detection API to get face landmarks and optionally cropped face URLs
2. Pass the landmarks_str value to Face Swap API as the opts parameter
3. When using return_face_url=true, use crop_landmarks for the cropped face image

​

Error Handling

​

Common Errors

​

Handling Failed Requests

# Example error handling in Python

# For image detection (no num_frames needed)
response = requests.post(
    "https://openapi.akool.com/interface/detect-api/detect_faces",
    json={"url": "https://example.com/image.jpg"},
    headers={"x-api-key": "YOUR_API_KEY"}
)

# For video detection (num_frames recommended)
# response = requests.post(
#     "https://openapi.akool.com/interface/detect-api/detect_faces",
#     json={"url": "https://example.com/video.mp4", "num_frames": 10},
#     headers={"x-api-key": "YOUR_API_KEY"}
# )

result = response.json()
if result["error_code"] != 0:
    print(f"Error: {result['error_msg']}")
else:
    faces = result["faces_obj"]
    print(f"Detected {len(faces['0']['landmarks'])} faces")

​

Performance Considerations

​

Processing Time

• Images: Typically < 1 second
• Videos: Varies based on:
  • Number of frames requested
  • Video resolution
  • Number of faces per frame

​

Rate Limits

​

Optimization Tips

• Use appropriate num_frames value - more frames = longer processing time
• Use single_face=true when you only need one face
• Cache results when processing the same media multiple times
• Process videos in batches if analyzing many videos

​

Support

• Authentication Guide
• API Error Codes
• Face Swap Integration