Skip to main content
POST
/
detect
Face Detect (Legacy)
curl --request POST \
  --url https://sg3.akool.com/detect \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "single_face": false,
  "image_url": "https://d21ksh0k4smeql.cloudfront.net/IMG_6150-1696984459910-0610.jpeg",
  "img": ""
}
'
{
  "error_code": 123,
  "error_msg": "<string>",
  "landmarks": [
    [
      [
        123
      ]
    ]
  ],
  "landmarks_str": [
    "<string>"
  ],
  "region": [
    [
      123
    ]
  ],
  "seconds": 123,
  "trx_id": "<string>"
}
This endpoint will be deprecated in a future release. We recommend using the new Detect Faces API for all new integrations.The new endpoint provides:
  • Support for both images and videos
  • Base64 image input support
  • Cropped face image URLs (return_face_url option)
  • Single face mode (single_face option)
  • Better face tracking for videos
  • Improved performance and accuracy
Recommended Migration: Replace https://sg3.akool.com/detect with https://openapi.akool.com/interface/detect-api/detect_faces

​
Migration Guide

​
Old Request (Legacy)

POST https://sg3.akool.com/detect
{
  "single_face": false,
  "image_url": "https://example.com/image.jpg"
}

POST https://openapi.akool.com/interface/detect-api/detect_faces
{
  "url": "https://example.com/image.jpg",
  "single_face": false
}

​
Parameter Mapping

Legacy ParameterNew ParameterNotes
image_urlurlRenamed
imgimgSame
single_facesingle_faceSame
-num_framesNew: for video support
-return_face_urlNew: get cropped face URLs

​
Response Changes

The new API returns a slightly different response format: Legacy Response: 
{
  "error_code": 0,
  "error_msg": "",
  "landmarks": [...],
  "landmarks_str": [...],
  "region": [...],
  "seconds": 0.123,
  "trx_id": "xxx"
}
New Response: 
{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "faces_obj": {
    "0": {
      "landmarks": [...],
      "landmarks_str": [...],
      "region": [...],
      "removed": [],
      "frame_time": null,
      "face_urls": null,
      "crop_region": null,
      "crop_landmarks": null
    }
  }
}
The new API wraps face data in a faces_obj object keyed by frame index. For images, use faces_obj["0"] to access the face data.

​
Legacy API Documentation

The following documentation is for the legacy endpoint. For new integrations, we recommend using the new Detect Faces API.

​
Important Notes

  • single_face: Set to true to return only the largest face data, or false to return all detected faces. This parameter controls whether the API returns data for multiple faces or just the most prominent one.
  • image_url or img: You can choose to enter either the image URL or the base64 encoded image data
  • The landmarks_str value from the response should be used as the opts parameter in Face Swap APIs

​
Response Fields

  • landmarks: Array of face landmark coordinates
  • landmarks_str: String representation of landmarks (use this for opts parameter)
  • region: Face region bounding box coordinates
  • seconds: API processing time
  • trx_id: Transaction ID for tracking

​
Face Detect Response Code

Error CodeDescription
0Success
OtherCheck error_msg for details

Authorizations

​
x-api-key
string
header
required

Your API Key used for request authorization.

Body

application/json
​
single_face
boolean
required

Set to true to return only the largest face data, or false to return all detected faces.

​
image_url
string

Image link. You can choose to enter this parameter or the img parameter.

​
img
string

Image base64 information. You can choose to enter this parameter or the image_url parameter.

Response

200 - application/json

Face detection completed

​
error_code
integer

Interface returns business status code (0: success)

​
error_msg
string

Error message of this API

​
landmarks
number[][][]

Key point data of face

​
landmarks_str
string[]

Landmark string representation

​
region
number[][]

Face region coordinates

​
seconds
number

API time-consuming

​
trx_id
string

Transaction ID