Skip to main content
POST
/
detect
Face Detect
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 API is hosted on a different server (sg3.akool.com) than the main Face Swap APIs.

​
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. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded.

Body

application/json
​
single_face
boolean
required

Set to true to return only the largest face data, or false to return all detected faces. When true, the API will detect all faces but only return data for the most prominent (largest) face.

​
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