Detect Faces - Akool open api documents

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
    }
  }
}

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

Parameter	Type	Required	Default	Description
`url`	string	Yes*	-	Image or video URL (publicly accessible)
`img`	string	Yes*	-	Base64-encoded image data
`num_frames`	integer	No	5	Number of frames for video analysis
`return_face_url`	boolean	No	false	Return cropped face image URLs
`single_face`	boolean	No	false	Return 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

Field	Type	Description
`error_code`	integer	0 = success, 1 = error
`error_msg`	string	Status message
`faces_obj`	object	Face data keyed by frame index (“0”, “1”, etc.)

Face Frame Data

Field	Type	Description
`landmarks`	array	6-point landmarks for each face: Left Eye, Right Eye, Nose, Mouth Center, Left Mouth Corner, Right Mouth Corner
`landmarks_str`	array	First 4 landmarks as string format `"x1,y1:x2,y2:x3,y3:x4,y4"` - use this for Face Swap `opts` parameter
`region`	array	Bounding boxes `[x, y, width, height]`
`removed`	array	Faces no longer visible (video only)
`frame_time`	number/null	Timestamp in seconds (video only, null for images)
`face_urls`	array/null	Cropped face URLs (when `return_face_url=true`)
`crop_region`	array/null	Crop region in original image coordinates
`crop_landmarks`	array/null	Landmarks 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_code	error_msg	Description
0	SUCCESS	Success
1	Either ‘url’ or ‘img’ parameter must be provided	Missing input
1	Invalid URL format	Bad URL
1	Failed to download media from URL	Download 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.)

Show child attributes

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
  }
}

Face Detection API Overview Analyze Frames

​Request Parameters

​Response Format

​Response Fields

​Face Frame Data

​Examples

​Example 1: Basic Image Detection

​Example 2: Video Detection

​Example 3: Get Cropped Face URLs

​Example 4: Single Face Mode

​Error Responses

​Integration with Face Swap

​Best Practices

Authorizations

Body

Response

Request Parameters

Response Format

Response Fields

Face Frame Data

Examples

Example 1: Basic Image Detection

Example 2: Video Detection

Example 3: Get Cropped Face URLs

Example 4: Single Face Mode

Error Responses

Integration with Face Swap

Best Practices