All Products
Search

This Product

    Alibaba Cloud Model Studio:Emoji video generation API reference

    Document Center

    Alibaba Cloud Model Studio:Emoji video generation API reference

    Last Updated:Oct 28, 2025

    The emoji-v1 model generates facial Emoji videos from portrait images and preset template IDs.

    Important

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

    Model overview

    Model

    Description

    emoji-v1

    Generates facial videos from a detected portrait image, coordinates for the face and dynamic expression areas, and a template ID.

    Prerequisites

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

    2. Process the input image using Emoji image detection to get the coordinates of the face area and the dynamic expression area. These coordinates are required as input parameters.

    HTTP

    Because video generation is time-consuming (typically 1 to 5 minutes), the API uses asynchronous invocation. The process involves two core steps: Create a task and then Poll for the result. The steps are as follows:

    The time required depends on the number of tasks in the queue and the service execution status. Please wait for the task to complete.

    Step 1: Create a task and get the task ID

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

    Request parameters

    Generate an Emoji video

    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/en-US/20250912/uopnly/emoji-image-detection.png",
        "driven_id": "mengwa_kaixin",
        "face_bbox": [212,194,460,441],
        "ext_bbox": [63,30,609,575]
    }
}'
    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.

    X-DashScope-Async string (Required)

    The asynchronous processing configuration parameter. HTTP requests support only asynchronous processing. You must set this parameter to enable.

    Important

    If this request header is missing, the error message "current user api does not support synchronous calls" is returned.

    Request body

    model string (Required)

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

    input object (Required)

    The basic input information, such as the face image, face area, and emoji area.

    Properties

    image_url string (Required)

    The public URL of a frontal face image. The HTTP and HTTPS protocols are supported.

    Image requirements:

    • Format: JPEG, JPG, PNG, BMP, or WEBP.

    • Resolution: The width and height must be between 400 and 7,000 pixels.

    • File size: No larger than 10 MB.

    • The image must pass Emoji image detection.

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

    face_bbox array of integer (Required)

    The coordinates of the face area in the image. The format is [x1, y1, x2, y2] in pixels, corresponding to the top-left and bottom-right points.

    Set this parameter to the value of the output.bbox_face field from the Emoji Image Detection API response.

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

    ext_bbox array of integer (Required)

    The coordinates of the dynamic expression area. The aspect ratio of this area is about 1:1. The format is [x1, y1, x2, y2] in pixels, corresponding to the top-left and bottom-right points.

    Set this parameter to the value of the output.ext_bbox_face field in the Emoji image detection API response.

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

    Note: The dynamic expression area is the square area that the model focuses on during video generation. It is usually slightly larger than the face area, and includes some background and shoulders, to ensure a natural animation effect.

    driven_id string (Required)

    The ID of the preset template. For a list of valid values, see Appendix: List of template IDs.

    Example: mengwa_kaixin.

    Response parameters

    Successful response

    Save the task_id to query the task status and result.

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

    Error response

    The task creation failed. For more information, see Error messages to resolve the issue.

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

    output object

    Task output information.

    Properties

    task_id string

    The task ID. The query is valid for 24 hours.

    task_status string

    The task status.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN

    request_id string

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

    code string

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

    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.

    Step 2: Query the result by task ID

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

    Note

    • Polling suggestion: Video generation takes several minutes. Use a polling mechanism and set a reasonable query interval, such as 15 seconds, to retrieve the result.

    • Task status transition: PENDING (In queue) → RUNNING (Processing) → SUCCEEDED (Successful) or FAILED (Failed).

    • Result link: After the task is successful, a video link is returned. The link is valid for 24 hours. After you retrieve the link, immediately download and save the video to a permanent storage service, such as Alibaba Cloud OSS.

    • task_id validity: 24 hours. After this period, you cannot query the result, and the API returns a task status of UNKNOWN.

    Request parameters

    Query task results

    Replace 86ecf553-d340-4e21-xxxxxxxxx with the actual task ID.

    The API keys for the Singapore and Beijing regions are different. Obtain an API key.
    The following code provides the base_url for the Singapore region. If you use a model in the Beijing region, replace the base_url with https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    Headers

    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.

    URL path parameters

    task_id string (Required)

    The task ID.

    Response parameters

    Task successful

    Video URLs are retained for only 24 hours and are automatically purged after this period. You must save the generated videos promptly.

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

    If a task fails, task_status is set to FAILED, and an error code and message are provided. For more information, see Error messages to resolve the issue.

    {
    "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 query expired

    The task_id is valid for 24 hours. After this period, the query fails and the following error message is returned.

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

    output object

    Task output information.

    Properties

    task_id string

    The task ID. The query is valid for 24 hours.

    task_status string

    The task status.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN

    Status transitions during polling:

    • PENDING (In queue) → RUNNING (Processing) → SUCCEEDED (Successful) or FAILED (Failed).

    • The status of the first query is usually PENDING (In queue) or RUNNING (Processing).

    • If the status changes to SUCCEEDED, the response contains the generated video URL.

    • If the status is FAILED, check the error message and retry.

    submit_time string

    The time when the task was submitted. The format is YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    The time when the task started running. The format is YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    The time when the task was completed. The format is YYYY-MM-DD HH:mm:ss.SSS.

    video_url string

    The video URL. This parameter is returned only if task_status is SUCCEEDED.

    The link is valid for 24 hours. You can use this URL to download the video. The video is in MP4 format with H.264 encoding.

    code string

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

    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.

    usage object

    The usage statistics for the output. Only successful tasks are counted.

    Properties

    video_duration integer

    The duration of the generated video in seconds.

    Billing formula: Cost = Video duration in seconds × Unit price.

    video_ratio string

    The aspect ratio of the generated video. Fixed at `standard`, which indicates a 1:1 aspect ratio.

    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 information about how to resolve the issue.

    Appendix: List of template IDs

    Example of parameter settings: { "input": { "driven_id": "mengwa_kaixin" } }.

    Note

    • The following effects are generated by the Tongyi app, which integrates the Emoji model.

    • The Emoji model generates portrait videos that do not include the stickers or the texts.

    Template ID (driven_id)

    Effect preview

    Template ID (driven_id)

    Effect preview

    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