表情包Emoji映像檢測API參考 - Alibaba Cloud Model Studio

表情包emoji-detect-v1是一個映像合規性檢測模型，用於判斷輸入映像中的人物形象是否滿足“表情包Emoji模型”的要求。檢測通過後，該模型輸出人臉地區及擴充後的動態表情地區座標，供後續視頻產生使用。

重要本文檔僅適用於“中國大陸（北京）”地區。如需使用模型，需使用“中國大陸（北京）”地區的API Key。

模型概覽

模型名稱	模型簡介
emoji-detect-v1	檢測輸入的映像是否符合Emoji 視頻產生所需要的映像規範。檢測通過後，輸出人臉地區（face_bbox）和擴充後的動態表情地區（ext_bbox_face）座標，供視頻產生使用。

輸入映像要求

合規映像樣本（檢測通過）

映像要求	合規映像樣本
單人正面肖像面部無遮擋（如手、頭髮、飾品等）表情自然，無誇張表情頭部姿態端正，無大幅度傾斜

不合規映像樣本（檢測失敗）

臉部地區附近露出手部	存在面部遮擋	存在誇張表情	頭部傾斜角度過大

前提條件

您需要已準備工作：擷取與配置 API Key並配置API Key到環境變數（準備下線，併入配置 API Key）。

HTTP調用

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

請求參數

要求標頭（Headers）

Content-Typestring（必選）

請求內容類型。此參數必須設定為application/json。

Authorizationstring（必選）

請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值：Bearer sk-xxxx。

請求體（Request Body）

model string （必選）

模型名稱。固定為emoji-detect-v1。

input object （必選）

輸入的基本資料，如待檢測映像。

屬性

image_url string （必選）

待檢測映像的公網 URL。支援 HTTP 或 HTTPS 協議。

映像限制：

映像格式：JPEG、JPG、PNG、BMP、WEBP。
映像解析度：映像的寬度和高度範圍均在[400, 7000]像素之間。
檔案大小：不超過10MB。

樣本值：https://help-static-aliyun-doc.aliyuncs.com/xxx.png。

parameters object （必選）

影像處理參數。

屬性

ratio string （必選）

待檢測地區的長寬比。對於 Emoji 視頻產生，此值固定為 1:1。

樣本值：1:1。

人像合規檢測

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-%E5%9B%BE%E5%83%8F%E6%A3%80%E6%B5%8B.png"
    },
    "parameters": {
        "ratio":"1:1"
    }
  }'

響應參數

output object

任務輸出資訊。

屬性

bbox_face array of integer

檢測到的人臉地區座標，格式為 [x1, y1, x2, y2]，單位為像素，對應左上和右下兩個點的座標。僅在檢測通過時返回。

此值應作為Emoji 視頻產生介面 input.face_bbox 參數的值。

樣本值：[212,194,460,441]。

ext_bbox_face array of integer

擴充後的動態表情地區座標，格式為 [x1, y1, x2, y2]，單位為像素，對應左上和右下兩個點的座標。僅在檢測通過時返回。

此值應作為Emoji 視頻產生介面 input.ext_bbox 參數的值。

樣本值：[63,30,609,575]。

codestring

錯誤碼。僅在檢測不通過時返回，詳情請參見錯誤資訊。

messagestring

錯誤資訊。僅在檢測不通過時返回，詳情請參見錯誤資訊。

request_idstring

請求唯一標識。可用於請求明細溯源和問題排查。

usage object

輸出資訊統計。

屬性

image_count integer

本次請求檢測映像數量，固定為 1 張，用於計費。
無論檢測是否通過，只要請求成功就計費；請求失敗不計費。計費資訊詳見模型價格。

說明當映像因不合規而導致檢測不通過時，本次API調用仍會正常計費，因為模型已經執行了完整的檢測流程。

messagestring

請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。

request_idstring

請求唯一標識。可用於請求明細溯源和問題排查。

檢測通過

請求成功且檢測通過，將產生計費，介面會在響應中返回usage.image_count。

請儲存返回的 bbox_face 和 ext_bbox_face。這是下一步Emoji 視頻產生介面中input.face_bbox和input.ext_bbox參數的值。

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

檢測不通過

請求成功但人像檢測未通過，將產生計費，介面會在響應中返回usage.image_count。請參見錯誤資訊排查問題。

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

請求失敗

介面請求失敗，不計費。此時介面不返回usage.image_count。請參見錯誤資訊進行解決。

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

計費與限流

模型免費額度和計費單價請參見模型價格。
模型限流請參見限流。

錯誤碼

如果模型調用失敗並返回報錯資訊，請參見錯誤資訊進行解決。