EMO image detection API - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

The emo-detect-v1 model validates whether a portrait image meets the requirements for EMO video generation. Call this API to check your image before generating a video, and retrieve the bounding box coordinates required by the EMO video generation API.

Important

This API is available only in the China (Beijing) region. Use an API key created in the China (Beijing) region.

How it works

Send a portrait image URL to the detection endpoint.
The API validates the image against the EMO model's portrait specifications.
If the image passes, the response includes face_bbox and ext_bbox coordinates. Pass these values directly to the EMO video generation API as request parameters.

Prerequisites

An activated Alibaba Cloud Model Studio account with an API key. See Create an API key.

Input requirements

Requirement	Specification
Format	JPG, JPEG, PNG, BMP, or WebP
Minimum resolution	Shortest side >= 400 px
Maximum resolution	Longest side <= 7,000 px
Input method	HTTP URL only. Local file paths are not supported.

API endpoint

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/face-detect

Request parameters

Headers

Parameter	Type	Required	Description
Content-Type	String	Yes	Set to `application/json`.
Authorization	String	Yes	Your API key in Bearer format: `Bearer <your-api-key>`.

Body

Parameter	Type	Required	Description
model	String	Yes	Set to `emo-detect-v1`.
input.image_url	String	Yes	HTTP URL of the portrait image to validate. The image must meet the format and resolution requirements listed in Input requirements.
parameters.ratio	String	Yes	Aspect ratio for validation. Default: `"1:1"`. Valid values: `"1:1"` (profile picture), `"3:4"` (half-body portrait).

Response parameters

Success response parameters

Parameter	Type	Description
output.check_pass	Boolean	Validation result. `true`: the image meets the portrait specifications. `false`: the image does not meet the specifications.
output.face_bbox	Array	Face bounding box coordinates `[x1, y1, x2, y2]`, where `(x1, y1)` is the upper-left corner and `(x2, y2)` is the lower-right corner. Returned only when `check_pass` is `true`. Pass this value to the EMO video generation API.
output.ext_bbox	Array	Dynamic area bounding box coordinates `[x1, y1, x2, y2]`. The aspect ratio matches the `ratio` value in your request. Returned only when `check_pass` is `true`. Pass this value to the EMO video generation API.
usage.image_count	Integer	Number of images processed. Used for billing.
request_id	String	Unique request identifier for troubleshooting.

Error response parameters

These parameters are returned only when the request fails.

Parameter	Type	Description
code	String	Error code. For details, see Error messages.
message	String	Error description. For details, see Error messages.

Examples

Request

Before running the command, set your API key as an environment variable:

export DASHSCOPE_API_KEY=<your-api-key>

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/face-detect' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "emo-detect-v1",
  "input": {
    "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251225/onmomb/emo.png"
  },
  "parameters": {
    "ratio": "1:1"
  }
}'

Response: image passed

When the image meets the portrait specifications, check_pass is true and the response includes both bounding boxes:

{
    "output": {
        "check_pass": true,
        "face_bbox": [302, 286, 610, 593],
        "ext_bbox": [71, 9, 840, 778]
    },
    "usage": {
        "image_count": 1
    },
    "request_id": "c56f62df-724e-9c19-96bd-xxxxxx"
}

Use face_bbox and ext_bbox from this response as input parameters in your EMO video generation request.

Response: image failed

When the image does not meet the portrait specifications, check_pass is false:

{
    "output": {
        "check_pass": false,
        "code": "",
        "message": ""
    },
    "usage": {
        "image_count": 1
    },
    "request_id": "c56f62df-724e-9c19-96bd-xxxxxx"
}

Response: request error

When the request is invalid (for example, a missing or incorrect API key), the response contains an error code and message:

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

For a full list of error codes, see Error messages.

Error codes

For error codes and troubleshooting, see Error messages.