Emoji image detection API reference - Alibaba Cloud Model Studio

This document applies only to the China (Beijing) region. To use the model, you must use an API key for the China (Beijing) region.

Model overview

Model	Description
emoji-detect-v1	Detects whether an input image meets specifications required for Emoji video generation. The model returns face area (bbox_face) and extended expression area (ext_bbox_face) coordinates for video generation.

Input image requirements

Example of a compliant image (detection passed)

Image requirements	Compliant example
Single front-facing portrait Face is not occluded (by objects such as hands, hair, or accessories) Natural expression, no exaggerated expressions Head is upright, without significant tilting

Image requirements

Compliant example

Single front-facing portrait
Face is not occluded (by objects such as hands, hair, or accessories)
Natural expression, no exaggerated expressions
Head is upright, without significant tilting

Examples of non-compliant images (detection failed)

Hand visible near the face

Face is occluded

Exaggerated expression

Excessive head tilt

Prerequisites

Obtain an API key and export the API key as an environment variable.

HTTP

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

Request parameters

Request headers

Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Request body

model string (Required)Set to emoji-detect-v1.input object (Required)The input image to detect.

Properties

image_url string (Required)Public URL of the image (HTTP/HTTPS supported).Limits:

Image format: JPEG, JPG, PNG, BMP, or WEBP.
Image resolution: The width and height of the image must be between 400 and 7,000 pixels.
File size: No larger than 10 MB.

Example: https://help-static-aliyun-doc.aliyuncs.com/xxx.png.

parameters object (Required)Detection parameters.

Properties

ratio string (Required)Aspect ratio of detection area. For Emoji video, set to 1:1.Example: 1:1.

Portrait compliance detection

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": "emoji-detect-v1",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250912/uopnly/emoji-image-detection.png"
    },
    "parameters": {
        "ratio":"1:1"
    }
  }'

Response parameters

output objectTask output information.

Properties

bbox_face array of integerFace area coordinates in pixels: [x1, y1, x2, y2] (upper-left and lower-right points). Returned only when detection passes.Use for input.face_bbox in Emoji video generation API.Example: [212,194,460,441].ext_bbox_face array of integerExtended expression area coordinates in pixels: [x1, y1, x2, y2] (upper-left and lower-right points). Returned only when detection passes.Use for input.ext_bbox in Emoji video generation API.Example: [63,30,609,575].code stringError code (returned when detection fails). See Error codes for details.message stringError message (returned when detection fails). See Error codes for details.

request_id stringUnique request identifier for tracing and troubleshooting.usage objectOutput statistics.

Properties

image_count integerNumber of images detected (always 1, used for billing). Successful requests incur charges regardless of detection result; failed requests do not. See Model pricing for billing details.

Non-compliant images still incur charges as detection was completed.

message stringDetailed error message. Returned only for failed requests. See Error codes.request_id stringUnique request identifier for tracing and troubleshooting.

Detection passed
Detection failed
Request failed

When detection passes, save bbox_face and ext_bbox_face for use in subsequent Emoji video generation (input.face_bbox and input.ext_bbox parameters). Charges apply (see usage.image_count).

{
    "output": {
        "bbox_face": [212,194,460,441],
        "ext_bbox_face": [63,30,609,575]
    },
    "usage": {
        "image_count": 1
    },
    "request_id": "78becbc4-f7f7-41ea-9e38-xxxxxx"
}

When detection fails, charges still apply (see usage.image_count). For troubleshooting, see Error Messages.

{
    "output": {
        "code": "InvalidFile.FacePose",
        "message": "The pose of the detected face is invalid, please upload other image with the expected oriention."
    },
    "usage": {
        "image_count": 1
    },
    "request_id": "ed0d0d8f-e55a-4144-b855-xxxxxx"
}

Request failures do not incur charges (no usage.image_count returned). For troubleshooting, see Error Messages.

{
    "request_id": "5e1fefbd-fa7a-4e59-82a0-xxxxxx",
    "code": "InvalidParameter",
    "message": "Required body invalid, please check the request body format."
}

Billing and rate limiting

For the free quota and unit price for the model, see Recommended models.
For rate limits, see Rate limiting.

Error codes

For error troubleshooting, see Error codes.

​Model overview

​Input image requirements

​Prerequisites

​HTTP

Request parameters

Request headers

Request body

Response parameters

​Billing and rate limiting

​Error codes

Model overview

Input image requirements

Prerequisites

HTTP

Billing and rate limiting

Error codes