All Products
Search

This Product

    Alibaba Cloud Model Studio:Emoji image detection API reference

    Document Center

    Alibaba Cloud Model Studio:Emoji image detection API reference

    Last Updated:Oct 28, 2025

    emoji-detect-v1 is used for image compliance detection. It checks whether the person in an input image meets the requirements for the Emoji model. If the image passes detection, the model outputs the coordinates of the face area and the extended dynamic area.

    Important

    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 the specifications required for Emoji video generation.
    If the detection passes, the model outputs the coordinates of the face area (bbox_face) and the extended dynamic expression area (ext_bbox_face) for use in 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.png

    Examples of non-compliant images (detection failed)

    Hand visible near the face

    Face is occluded

    Exaggerated expression

    Excessive head tilt

    image.png

    image.png

    image.png

    image.png

    Prerequisites

    You must obtain an API key and set the API key as an environment variable.

    HTTP

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

    Request parameters

    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"
    }
  }'
    Request headers

    Content-Type string (Required)

    The content type of the request. Set this parameter to application/json.

    Authorization string (Required)

    The identity authentication credentials for the request. This API uses an Model Studio API key for identity authentication. Example: Bearer sk-xxxx.

    Request body

    model string (Required)

    The model name. Set this parameter to emoji-detect-v1.

    input object (Required)

    The input information, which includes the image to be detected.

    Properties

    image_url string (Required)

    The public URL of the image to be detected. The HTTP and HTTPS protocols are supported.

    Image 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)

    Image editing parameters.

    Properties

    ratio string (Required)

    The aspect ratio of the area to be detected. For Emoji video generation, set this parameter to 1:1.

    Example: 1:1.

    Response parameters

    Detection passed

    If the request is successful and the detection passes, the request will incur charges. The API returns usage.image_count in the response.

    Save the returned bbox_face and ext_bbox_face values. These values are used for the input.face_bbox and input.ext_bbox parameters in the subsequent Emoji video generation.

    {
    "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"
}

    Detection failed

    If a request is successful but face detection fails, the request will incur charges, and the API returns usage.image_count in the response. To troubleshoot the issue, 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 failed

    If an API request fails, it will not incur charges, and the API does not return usage.image_count. To resolve the error, see Error Messages.

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

    output object

    Task output information.

    Properties

    bbox_face array of integer

    The coordinates of the detected face area. The format is [x1, y1, x2, y2] in pixels, which correspond to the upper-left and lower-right points. This parameter is returned only if the detection passes.

    Use this value for the input.face_bbox parameter of the Emoji video generation API.

    Example: [212,194,460,441].

    ext_bbox_face array of integer

    The coordinates of the extended dynamic expression area. The format is [x1, y1, x2, y2] in pixels, which correspond to the upper-left and lower-right points. This parameter is returned only if the detection passes.

    Use this value for the input.ext_bbox parameter of the Emoji video generation API.

    Example: [63,30,609,575].

    code string

    The error code that is returned if the check fails. For more information, see Error messages.

    message string

    The error message that is returned if the check fails. For more information, see Error messages.

    request_id string

    The unique request ID. You can use this ID to trace and troubleshoot issues.

    usage object

    Output statistics.

    Properties

    image_count integer

    The number of images detected in the request. The value is 1 and is used for billing.
    The request will incur changes if it is successful, regardless of whether the detection passes or not. The request will not incur changes if it fails. For more information about billing, see Model pricing.

    Note

    If an image fails detection because it is non-compliant, the API call will still incur changes, because the model completed the full detection process.

    message string

    The detailed information about a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

    request_id string

    The unique request ID. You can use this ID to trace and troubleshoot issues.

    Billing and rate limiting

    Error codes

    If a model call fails and an error message is returned, see Error messages for troubleshooting solutions.