Skip to main content
POST
/
detect_faces
curl --request POST \
  --url https://openapi.akool.com/interface/detect-api/detect_faces \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "url": "https://example.com/image.jpg"
}
'
{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [
        [
          [
            120,
            85
          ],
          [
            180,
            88
          ],
          [
            150,
            130
          ],
          [
            150,
            165
          ],
          [
            125,
            165
          ],
          [
            175,
            168
          ]
        ]
      ],
      "landmarks_str": [
        "120,85:180,88:150,130:150,165"
      ],
      "region": [
        [
          80,
          50,
          150,
          180
        ]
      ],
      "removed": [],
      "frame_time": null,
      "face_urls": null,
      "crop_region": null,
      "crop_landmarks": null
    }
  }
}
Detect faces in images and videos with 6-point landmarks. Supports URL and base64 input, with optional cropped face URLs.

​
Request Parameters

ParameterTypeRequiredDefaultDescription
urlstringYes*-Image or video URL (publicly accessible)
imgstringYes*-Base64-encoded image data
num_framesintegerNo5Number of frames for video analysis
return_face_urlbooleanNofalseReturn cropped face image URLs
single_facebooleanNofalseReturn only the largest face
Either url or img must be provided. If both are provided, url takes priority.

​
Response Format

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [[[120, 85], [180, 88], [150, 130], [150, 165], [125, 165], [175, 168]]],
      "landmarks_str": ["120,85:180,88:150,130:150,165"],
      "region": [[80, 50, 150, 180]],
      "removed": [],
      "frame_time": null,
      "face_urls": null,
      "crop_region": null,
      "crop_landmarks": null
    }
  }
}

​
Response Fields

FieldTypeDescription
error_codeinteger0 = success, 1 = error
error_msgstringStatus message
faces_objobjectFace data keyed by frame index (“0”, “1”, etc.)

​
Face Frame Data

FieldTypeDescription
landmarksarray6-point landmarks for each face: Left Eye, Right Eye, Nose, Mouth Center, Left Mouth Corner, Right Mouth Corner
landmarks_strarrayFirst 4 landmarks as string format "x1,y1:x2,y2:x3,y3:x4,y4" - use this for Face Swap opts parameter
regionarrayBounding boxes [x, y, width, height]
removedarrayFaces no longer visible (video only)
frame_timenumber/nullTimestamp in seconds (video only, null for images)
face_urlsarray/nullCropped face URLs (when return_face_url=true)
crop_regionarray/nullCrop region in original image coordinates
crop_landmarksarray/nullLandmarks relative to cropped image

​
Examples

​
Example 1: Basic Image Detection

Request: 
{
  "url": "https://example.com/photo.jpg"
}
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"],
      "region": [[300, 200, 150, 180]],
      "removed": [],
      "frame_time": null
    }
  }
}

​
Example 2: Video Detection

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

​
Example 3: Get Cropped Face URLs

Request: 
{
  "url": "https://example.com/photo.jpg",
  "return_face_url": true
}
Response: 
{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [[[120, 85], [180, 88], [150, 130], [150, 165], [125, 165], [175, 168]]],
      "landmarks_str": ["120,85:180,88:150,130:150,165"],
      "region": [[80, 50, 150, 180]],
      "removed": [],
      "frame_time": null,
      "face_urls": ["https://s3.example.com/faces/face_detect_0.jpg"],
      "crop_region": [[30, 0, 250, 280]],
      "crop_landmarks": ["90,85:150,88:120,130:120,165"]
    }
  }
}

​
Example 4: Single Face Mode

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

​
Error Responses

error_codeerror_msgDescription
0SUCCESSSuccess
1Either ‘url’ or ‘img’ parameter must be providedMissing input
1Invalid URL formatBad URL
1Failed to download media from URLDownload failed

​
Integration with Face Swap

Use landmarks_str directly as the opts parameter in Face Swap API: 
import requests

# Detect faces
response = requests.post(
    "https://openapi.akool.com/interface/detect-api/detect_faces",
    json={"url": "https://example.com/target.jpg", "return_face_url": True},
    headers={"x-api-key": "YOUR_API_KEY"}
)

result = response.json()
if result["error_code"] == 0:
    frame_data = result["faces_obj"]["0"]
    # Use for Face Swap API
    target_image = {
        "path": frame_data["face_urls"][0],
        "opts": frame_data["crop_landmarks"][0]
    }

​
Best Practices

  • URL Requirements: Use HTTPS, ensure publicly accessible
  • Video num_frames: Short videos (5-10), Medium (10-20), Long (20-50)
  • Performance: Use single_face=true when only one face needed

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>

URL of the video or image to process. The media type will be auto-detected based on the file extension. Either url or img must be provided. If both are provided, url takes priority.

Example:

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

​
img
string

Base64-encoded image data. Supports both plain base64 string and data URI format (e.g., "data:image/jpeg;base64,..."). Either url or img must be provided. If both are provided, url takes priority.

Example:

"data:image/jpeg;base64,/9j/4AAQSkZJRg..."

​
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

​
return_face_url
boolean
default:false

Whether to return cropped face image URLs. When set to true, the response will include:

  • face_urls: URLs of cropped face images
  • crop_region: The region used for cropping in original image coordinates
  • crop_landmarks: Landmarks relative to the cropped image
Example:

false

​
single_face
boolean
default:false

When set to true, only returns the largest face (by area) in each frame. Useful when you only need the main/primary face in the image or video.

Example:

false

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.)

Example:
{
  "0": {
    "landmarks": [
      [
        [120, 85],
        [180, 88],
        [150, 130],
        [150, 165],
        [125, 165],
        [175, 168]
      ]
    ],
    "landmarks_str": ["120,85:180,88:150,130:150,165"],
    "region": [[80, 50, 150, 180]],
    "removed": [],
    "frame_time": null,
    "face_urls": null,
    "crop_region": null,
    "crop_landmarks": null
  }
}