> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akool.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Face Detect (Legacy)

> Detect faces in images and get landmark information

<Warning>
  **This endpoint will be deprecated in a future release.** We recommend using the new [Detect Faces API](/ai-tools-suite/face-detection/detect-faces) 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`
</Warning>

## Migration Guide

### Old Request (Legacy)

```json theme={null}
POST https://sg3.akool.com/detect
{
  "single_face": false,
  "image_url": "https://example.com/image.jpg"
}
```

### New Request (Recommended)

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

### Parameter Mapping

| Legacy Parameter | New Parameter     | Notes                      |
| ---------------- | ----------------- | -------------------------- |
| `image_url`      | `url`             | Renamed                    |
| `img`            | `img`             | Same                       |
| `single_face`    | `single_face`     | Same                       |
| -                | `num_frames`      | New: for video support     |
| -                | `return_face_url` | New: get cropped face URLs |

### Response Changes

The new API returns a slightly different response format:

**Legacy Response**:

```json theme={null}
{
  "error_code": 0,
  "error_msg": "",
  "landmarks": [...],
  "landmarks_str": [...],
  "region": [...],
  "seconds": 0.123,
  "trx_id": "xxx"
}
```

**New Response**:

```json theme={null}
{
  "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
    }
  }
}
```

<Note>
  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.
</Note>

***

## Legacy API Documentation

<Info>
  The following documentation is for the legacy endpoint. For new integrations, we recommend using the [new Detect Faces API](/ai-tools-suite/face-detection/detect-faces).
</Info>

## 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 Code | Description                  |
| ---------- | ---------------------------- |
| 0          | Success                      |
| Other      | Check error\_msg for details |


## OpenAPI

````yaml POST /detect
openapi: 3.0.3
info:
  title: Face Detect API (Legacy)
  description: Legacy API for detecting faces in images
  version: 1.0.0
servers:
  - url: https://sg3.akool.com
    description: Face detection server
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /detect:
    post:
      tags:
        - Face Detection (Legacy)
      summary: Face Detect (Legacy)
      description: >
        **Note**: This endpoint will be deprecated in a future release. We
        recommend using the new [Detect Faces
        API](https://openapi.akool.com/interface/detect-api/detect_faces) for
        all new integrations.


        The new endpoint provides:

        - Support for both images and videos

        - Base64 image input support

        - Cropped face image URLs

        - Single face mode

        - Better face tracking for videos


        ---


        Legacy endpoint to detect faces in images and get landmark information.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FaceDetectRequest'
            example:
              single_face: false
              image_url: >-
                https://d21ksh0k4smeql.cloudfront.net/IMG_6150-1696984459910-0610.jpeg
              img: ''
      responses:
        '200':
          description: Face detection completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceDetectResponse'
components:
  schemas:
    FaceDetectRequest:
      type: object
      required:
        - single_face
      properties:
        single_face:
          type: boolean
          description: >-
            Set to true to return only the largest face data, or false to return
            all detected faces.
        image_url:
          type: string
          description: >-
            Image link. You can choose to enter this parameter or the img
            parameter.
        img:
          type: string
          description: >-
            Image base64 information. You can choose to enter this parameter or
            the image_url parameter.
    FaceDetectResponse:
      type: object
      properties:
        error_code:
          type: integer
          description: 'Interface returns business status code (0: success)'
        error_msg:
          type: string
          description: Error message of this API
        landmarks:
          type: array
          items:
            type: array
            items:
              type: array
              items:
                type: number
          description: Key point data of face
        landmarks_str:
          type: array
          items:
            type: string
          description: Landmark string representation
        region:
          type: array
          items:
            type: array
            items:
              type: number
          description: Face region coordinates
        seconds:
          type: number
          description: API time-consuming
        trx_id:
          type: string
          description: Transaction ID
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your API Key used for request authorization.
    BearerAuth:
      type: http
      scheme: bearer
      description: Your API Key used for request authorization.

````