Human image detection-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Important

This document applies only to the China (Beijing) region. Use an API key from this region.

Human image detection

Note

Supported realm/task: aigc/facechain portrait generation

This service detects faces in uploaded images to determine whether they meet the standards for FaceChain fine-tuning. The detection analyzes multiple dimensions, such as face count, size, angle, lighting, and definition. The service supports image groups as input and returns a detection result for each image.

This model is an optional step in the task flow. You can integrate it as needed.

Image selection recommendations

Face count: Each image must contain only one face. Images with multiple faces or no faces are not supported.
Face quality: The image must contain a frontal face that is larger than 128 × 128 pixels and not blocked by objects, such as sunglasses or hands. Avoid heavy makeup and excessive retouching.
Image quality: The image resolution must be between 256 × 256 pixels and 4096 × 4096 pixels. The file size cannot exceed 5 MB. The image must be clear and free of complex lighting and shades.

Model overview

Model name	Model description
facechain-facedetect	Detects faces in uploaded images to check if they meet the standards for FaceChain fine-tuning. The detection analyzes multiple dimensions, including face count, size, angle, lighting, and definition. It supports image groups as input and returns a detection result for each image.

HTTP API

Feature description

This model provides a synchronous API. After you submit a job, the results are returned in the response.

Prerequisites

You must activate the service and obtain an API key. For more information, see Obtain and configure an API key.

Note

API limit: A single account, including an Alibaba Cloud account and its RAM users, is limited to 5 queries per second (QPS) for the job submission API.

Job submission API call

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/vision/facedetection/detect

Replace {WorkspaceId} with your actual workspace ID.

Request parameters

Parameter Passing	Field	Type	Required	Description	Example
Header	Content-Type	String	Yes	Request type: application/json	application/json
Header	Authorization	String	Yes	API key. Example: Bearer d1**2a	Bearer d1**2a
Body	model	String	Yes	The model to call. This is a static field.	facechain-facedetect
Body	input.images	Array	Yes	The URL of the input image. The resolution must be between 256 × 256 pixels and 4096 × 4096 pixels. The file size cannot exceed 5 MB. Supported formats include JPEG, PNG, JPG, and WEBP. The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.	"images": [ "http://a/a.jpg", "http://b/b.jpg", "http://c/c.jpg", ]

Response parameters

Field	Type	Description	Example
output.is_face	Array	The detection results for the list of submitted images. The results correspond to the input images in order. true: The detection passed. false: The detection failed.	"is_face":[ true, true, false, false ]
output.failed_reason	Array	The reason why the image detection failed.	no face detected
usage	Object	The billing usage statistics for this request. The facechain-facedetect model is currently free for a limited time, so the usage information is empty.	-
request_id	String	The unique system code for this request.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Request example

The following example shows a cURL command script that you can use to call this model.

Note

Replace your-dashscope-api-key in the example with your API key to ensure that the code runs correctly.

curl

curl --location --request POST 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/vision/facedetection/detect' \
--header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{
  "model": "facechain-facedetect",
  "input": {
    "images": [
      "http://finetune-swap-wulanchabu.oss-cn-wulanchabu.aliyuncs.com/zhicheng/tmp/1E1D5AFA-3C3A-4B6F-ABD6-8742CA983C42.png",
      "http://finetune-swap-wulanchabu.oss-cn-wulanchabu.aliyuncs.com/zhicheng/tmp/3.JPG",
      "http://finetune-swap-wulanchabu.oss-cn-wulanchabu.aliyuncs.com/zhicheng/tmp/F2EA3984-6EE2-44CD-928F-109B7276BCB6.png"
    ]
  },
  "parameters": {
  }
}'

Response example

JSON

{
  "output": {
    "is_face": [true, false, true],
    "failed_reason": ["", "no face detected", ""]
  },
  "usage": {},
  "request_id": "549e0573-f630-9c17-8df2-08f605b4a646"
}

Error response example

If an error occurs during a job submission request, the response includes the `code` and `message` fields to indicate the cause of the error.

JSON

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

Status codes

For information about the common status codes for the Large Model Service Platform, see Error Messages.

HTTP return code*	Error code (code)	Error message (message)	Description
400	InvalidParameter	Required parameter(s) missing or invalid, please check the request parameters.	The API call parameters are invalid.