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:Mar 15, 2026

    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 portrait images using face coordinates, dynamic expression area coordinates, and template IDs.

    Prerequisites

    1. Get an API key and export 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

    Video generation typically takes 1 to 5 minutes, so the API uses asynchronous invocation. Create a task, then poll for results.

    Processing time varies based on queue length and service status. Wait for task completion.

    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/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 (Required)

    The content type of the request. Must be application/json.

    Authorization string (Required)

    The authentication credentials using a Model Studio API key.

    Example: Bearer sk-xxxx

    X-DashScope-Async string (Required)

    Enables asynchronous processing. Must be enable as HTTP requests support only asynchronous processing.

    Important

    Returns "current user api does not support synchronous calls" error if not included.
    Request body

    model string (Required)

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

    input object (Required)

    Basic input information, such as face image, face area, and emoji area.

    Properties

    image_url string (Required)

    Public URL of a frontal face image. HTTP and HTTPS 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)

    Face area coordinates in the image. The format is [x1, y1, x2, y2] in pixels (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)

    Dynamic expression area coordinates. The aspect ratio is about 1:1. The format is [x1, y1, x2, y2] in pixels (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 typically slightly larger than the face area, including background and shoulders for natural animation.

    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

    Task creation failed. See error codes to resolve the issue.

    {
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

    output object

    Task status and results.

    Properties

    task_id string

    The ID of the task. Can be used to query the task for up to 24 hours.

    task_status string

    The status of the task.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: Task does not exist or status is unknown

    request_id string

    Unique identifier for the request. Use for tracing and troubleshooting issues.

    code string

    The error code. Returned only when the request fails. See error codes for details.

    message string

    Detailed error message. Returned only when the request fails. See error codes for details.

    Step 2: Query the result by task ID

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

    Note

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

    • Task status transition: PENDING → RUNNING → SUCCEEDED or FAILED.

    • Result URL: After the task is successful, a video URL is returned. The URL is valid for 24 hours. After you retrieve the URL, you must immediately download and save the video to a permanent storage service, such as Object Storage Service (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.

    API keys are region-specific. See API key documentation for details.
    For models in the Beijing region, replace base_url with 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 (Required)

    The authentication credentials using a Model Studio API key.

    Example: Bearer sk-xxxx
    URL path parameters

    task_id string (Required)

    The ID of the task to query.

    Response parameters

    Task successful

    Video URLs are retained for only 24 hours and then automatically purged. Save 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

    When a task fails, task_status is set to FAILED with an error code and message. See error codes 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, queries fail and return the following error message.

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

    output object

    Task status and results.

    Properties

    task_id string

    The ID of the task. Can be used to query the task for up to 24 hours.

    task_status string

    The status of the task.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: Task does not exist or status is unknown

    Status transitions during polling:

    • PENDING → RUNNING → SUCCEEDED or FAILED

    • First query typically returns PENDING or RUNNING

    • SUCCEEDED status includes the generated video URL in the response

    • FAILED status requires checking the error message and retrying

    submit_time string

    The time when the task was submitted. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    The time when the task started running. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    The time when the task was completed. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    video_url string

    The URL of the generated video. Returned only when task_status is SUCCEEDED.

    URL is valid for 24 hours. Use to download the video in MP4 format with H.264 encoding.

    code string

    The error code. Returned only when the request fails. See error codes for details.

    message string

    Detailed error message. Returned only when the request fails. See error codes for details.

    usage object

    Output usage statistics (successful tasks only).

    Properties

    video_duration integer

    The duration of the generated video in seconds.

    Billing: Cost = Video duration (seconds) × Unit price.

    video_ratio string

    Video aspect ratio. Fixed at `standard` (1:1).

    request_id string

    Unique identifier for the request. Use for tracing and troubleshooting issues.

    Billing and rate limiting

    Error codes

    If a model call fails, see Error messages to resolve the error.

    Appendix: List of template IDs

    Example: { "input": { "driven_id": "mengwa_kaixin" } }.

    Note

    • Preview effects generated by Tongyi app (integrates Emoji model).

    • Generated videos exclude stickers and text overlays.

    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