全部產品
Search

搜尋本產品

    Alibaba Cloud Model Studio：Emoji 視頻產生API參考

    文件中心

    Alibaba Cloud Model Studio：Emoji 視頻產生API參考

    更新時間：Oct 25, 2025

    表情包emoji-v1模型可基於人物肖像圖片和預設模板ID，產生人臉表情包視頻。

    重要

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

    模型概覽

    模型名稱

    模型簡介

    emoji-v1

    輸入通過檢測的人物肖像圖片、對應的人臉地區、動態表情地區座標以及表情包模板ID，產生人臉表情包視頻。

    前提條件

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

    2. 輸入映像已通過Emoji 映像檢測，並獲得對應人臉地區和動態表情地區的座標作為入參。

    HTTP調用

    由於視頻產生任務耗時較長（通常為1-5分鐘），API採用非同步呼叫。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟，具體如下：

    模型耗時受限於排隊任務數和服務執行情況，請在擷取結果時耐心等待。

    步驟1：建立任務擷取任務ID

    POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

    請求參數

    表情包視頻產生

    curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--data '{
    "model": "emoji-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",
        "driven_id": "mengwa_kaixin",
        "face_bbox": [212,194,460,441],
        "ext_bbox": [63,30,609,575]
    }
}'
    要求標頭（Headers）

    Content-Type string （必選）

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

    Authorization string（必選）

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

    X-DashScope-Async string （必選）

    非同步處理配置參數。HTTP請求只支援非同步，必須設定為enable。

    重要

    缺少此要求標頭將報錯：“current user api does not support synchronous calls”。

    請求體（Request Body）

    model string （必選）

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

    input object （必選）

    輸入的基本資料，如人臉映像、人臉地區、表情包地區等。

    屬性

    image_url string （必選）

    人臉正面肖像映像的公網 URL。支援 HTTP 或 HTTPS 協議。

    映像限制：

    • 映像格式：JPEG、JPG、PNG、BMP、WEBP。

    • 映像解析度：映像的寬度和高度均在[400, 7000]像素之間。

    • 檔案大小：不超過10MB。

    • 此映像必須通過Emoji 映像檢測。

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

    face_bbox array of integer （必選）

    圖片中人臉地區座標，格式為 [x1, y1, x2, y2]，單位為像素，對應左上和右下兩個點的座標。

    此參數需填入Emoji 映像檢測介面響應中的output.bbox_face 欄位的值。

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

    ext_bbox array of integer （必選）

    動態表情地區座標，該地區的寬高比約為1:1，格式為 [x1, y1, x2, y2]，單位為像素，對應左上和右下兩個點的座標。

    此參數需填入Emoji 映像檢測介面響應中的output.ext_bbox_face欄位的值。

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

    說明：動態表情地區指的是模型進行視頻產生時實際關注的正方形映像地區，它通常比人臉地區稍大，以包含部分背景和肩膀，確保動畫效果自然。

    driven_id string （必選）

    預設模板ID，可選值參見表情包模板ID列表。

    樣本值：mengwa_kaixin。

    響應參數

    成功響應

    請儲存 task_id，用於查詢任務狀態與結果。

    {
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

    異常響應

    建立任務失敗，請參見錯誤資訊進行解決。

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

    output object

    任務輸出資訊。

    屬性

    task_id string

    任務ID。查詢有效期間24小時。

    task_status string

    任務狀態。

    枚舉值

    • PENDING：任務排隊中

    • RUNNING：任務處理中

    • SUCCEEDED：任務執行成功

    • FAILED：任務執行失敗

    • CANCELED：任務已取消

    • UNKNOWN：任務不存在或狀態未知

    request_id string

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

    code string

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

    message string

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

    步驟2：根據任務ID查詢結果

    GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

    說明

    • 輪詢建議：視頻產生過程約需數分鐘，建議採用輪詢機制，並設定合理的查詢間隔（如 15 秒）來擷取結果。

    • 任務狀態流轉：PENDING（排隊中）→ RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。

    • 結果連結：任務成功後返回視頻連結，有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存（如阿里雲 OSS）。

    • task_id 有效期間：24小時，逾時後將無法查詢結果，介面將返回任務狀態為UNKNOWN。

    請求參數

    查詢任務結果

    請將86ecf553-d340-4e21-xxxxxxxxx替換為真實的task_id。

    新加坡和北京地區的API Key不同。準備工作：擷取與配置 API Key。
    以下為新加坡地區base_url，若使用北京地區的模型，需將base_url替換為https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx
    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    要求標頭（Headers）

    Authorization string（必選）

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

    URL路徑參數（Path parameters）

    task_id string（必選）

    任務ID。

    響應參數

    任務執行成功

    視頻URL僅保留24小時，逾時後會被自動清除，請及時儲存產生的視頻。

    {
    "request_id": "ad225054-6c94-47e5-9356-xxxxxxx",
    "output": {
        "task_id": "b56f509a-3ea9-4cfe-848d-xxxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-10-14 11:28:04.372",
        "scheduled_time": "2025-10-14 11:28:04.400",
        "end_time": "2025-10-14 11:29:03.924",
        "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xx.mp4?Expires=xxx"
    },
    "usage": {
        "video_duration": 2,
        "video_ratio": "standard"
    }
}

    任務執行失敗

    若任務執行失敗，task_status將置為 FAILED，並提供錯誤碼和資訊。請參見錯誤資訊進行解決。

    {
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

    任務查詢到期

    task_id查詢有效期間為 24 小時，逾時後將無法查詢，返回以下報錯資訊。

    {
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

    output object

    任務輸出資訊。

    屬性

    task_id string

    任務ID。查詢有效期間24小時。

    task_status string

    任務狀態。

    枚舉值

    • PENDING：任務排隊中

    • RUNNING：任務處理中

    • SUCCEEDED：任務執行成功

    • FAILED：任務執行失敗

    • CANCELED：任務已取消

    • UNKNOWN：任務不存在或狀態未知

    輪詢過程中的狀態流轉：

    • PENDING（排隊中） → RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。

    • 初次查詢狀態通常為 PENDING（排隊中）或 RUNNING（處理中）。

    • 當狀態變為 SUCCEEDED 時，響應中將包含產生的視頻url。

    • 若狀態為 FAILED，請檢查錯誤資訊並重試。

    submit_time string

    任務提交時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。

    scheduled_time string

    任務執行時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。

    end_time string

    任務完成時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。

    video_url string

    視頻URL。僅在 task_status 為 SUCCEEDED 時返回。

    連結有效期間24小時，可通過此URL下載視頻。視頻格式為MP4（H.264 編碼）。

    code string

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

    message string

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

    usage object

    輸出資訊統計，只對成功的結果計數。

    屬性

    video_duration integer

    產生視頻的時間長度，單位為秒。

    計費公式：費用 = 視頻秒數 × 單價。

    video_ratio string

    產生視頻的畫幅，固定為standard，表示產生1:1畫幅的視頻。

    request_id string

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

    計費與限流

    錯誤碼

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

    附錄：表情包模板ID列表

    參數設定樣本：{ "input": { "driven_id": "mengwa_kaixin" } }。

    說明

    • 以下產生效果，由整合了“表情包Emoji”的通義APP產生。

    • 表情包Emoji模型產生的內容為人物視頻，不包含貼紙和文字。

    模板 ID (driven_id)

    效果示意

    模板 ID (driven_id)

    效果示意

    mengwa_kaixin

    1_mengwa_kaixin

    dagong_zhuakuang

    10_dagong_zhuakuang

    mengwa_dengyan

    7_mengwa_dengyan

    dagong_wunai

    15_dagong_wunai

    mengwa_gandong

    16_mengwan_gandong

    dagong_weixiao

    17_dagong_weixiao

    mengwa_renzhen_1

    18_mengwa_renzhen_1

    dagong_ganji

    20_dagong_ganji

    mengwa_jidong

    8_mengwa_jidong

    jingdian_tiaopi

    4_jingdian_tiaopi

    mengwa_kun_1

    11_mengwa_kun_1

    jingdian_deyi_1

    5_jingdian_deyi_1

    mengwa_jiaoxie

    19_mengwa_renzhen_1

    jingdian_qidai

    6_jingdian_qidai

    dagong_kaixin

    2_dagong_kaixin

    jingdian_landuo_1

    12_jingdian_landuo_1

    dagong_yangwang

    3_dagong_yangwang

    jingdian_xianqi

    13_jingdian_xianqi

    dagong_kunhuo

    9_dagong_kunhuo

    jingdian_lei

    14_jingdian_lei