Detect Faces in Images

April 24, 2025

Table of contents

  1. Request Headers
  2. Request Body
  3. Responses
  4. Model
  5. Examples
  6. Try It

This endpoint detects faces in the provided image and returns face information, including positions and features. This is useful for identifying facial features prior to using them with POST /images/kolors with the face reference type.

You can execute an unlimited number of face detections for free. This feature is available for all Kling subscription plans, including the free one.

https://api.useapi.net/v1/kling/images/recognize-faces

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
Request Body 
{
  "email": "[email protected]",
  "imageReference": "https://example.com/image.jpg"
}

  • email is optional when only one account configured.
    However, if you have multiple accounts configured, this parameter becomes required.

  • imageReference is required, the URL of the image to analyze.
    You can upload images using POST /assets and use the returned URL here.

Responses

  • 200 OK

    {
  "status": 0,
  "message": "",
  "faceItems": [
    {
      "name": "face_0",
      "resources": [
        {
          "name": "face",
          "type": "image",
          "url": "https://s21-kling.klingai.com/...face_0.jpg",
          "marginTop": 0,
          "countInRow": 1
        },
        {
          "name": "face_feature",
          "type": "image",
          "url": "https://s21-kling.klingai.com/...face_feature_0.jpg",
          "marginTop": 0,
          "countInRow": 1
        }
      ],
      "arguments": [
        {
          "name": "face_bound",
          "value": "{\"x\":120,\"y\":80,\"width\":200,\"height\":240}"
        }
      ]
    }
  ],
  "mediaInfo": {
    "type": "image",
    "duration": 0,
    "width": 724,
    "height": 1268
  }
}

  • 400 Bad Request

    {
  "error": "Parameter imageReference is required"
}

  • 401 Unauthorized

    {
  "error": "Unauthorized",
  "code": 401
}

If the response contains faceItems, it means faces were detected in the image. Each face is listed with its position and features. The response will include:

  • status: 0 indicates success
  • faceItems: An array of detected faces, each with:
    • resources: Face images and feature information
    • arguments: Contains face bounding box coordinates
  • mediaInfo: Information about the original image
Model 
{ // TypeScript, all fields are optional
  status: number  // 0 for success
  message: string // Empty string on success, error message otherwise
  faceItems?: {
    name: string  // Face identifier (e.g., "face_0")
    resources: {
      name: string  // Resource type identifier (e.g., "face", "face_feature")
      type: string  // Resource type (typically "image")
      url: string   // URL to the resource
      marginTop: number // Display margin
      countInRow: number // Display count in row
    }[]
    arguments: {
      name: string  // Argument name (e.g., "face_bound")
      value: string // JSON string with facial bounds coordinates
    }[]
  }[]
  mediaInfo: {
    type: string  // Media type (typically "image")
    duration: number // Duration for video (0 for image)
    width: number // Image width in pixels
    height: number // Image height in pixels
  }
}
Examples 
  • curl -X POST "https://api.useapi.net/v1/kling/images/recognize-faces" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "email": "[email protected]",
     "imageReference": "https://example.com/image.jpg"
   }'

  • const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/images/recognize-faces"; 
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    imageReference: "https://example.com/image.jpg"
  })
});
const result = await response.json();
console.log("response", {response, result});

  • import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/images/recognize-faces"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "imageReference": "https://example.com/image.jpg"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
Try It