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:Jun 24, 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. Obtain 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)

    Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

    X-DashScope-Async string (Required)

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

    Important

    If this request header is missing, the error "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)

    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.

    {
    "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 task ID. Valid for queries for 24 hours.

    task_status string

    The status of the task.

    Enumeration values

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: The task does not exist or its status is unknown.

    request_id string

    Unique request identifier for tracing and troubleshooting.

    code string

    Error code. Returned only for failed requests. See Error codes.

    message string

    Detailed error message. Returned only for failed requests. See Error codes.

    Step 2: Query the result by task ID

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

    Note

    • Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.

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

    • Result link: After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.

    • task_id validity: 24 hours. After this period, queries return the task status as UNKNOWN.

    Request parameters

    Query task results

    Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id.

    API keys are different for each region. For more information, see Obtain an API key.
    If you use a model in the China (Beijing) region, replace base_url with https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx, where WorkspaceId is your actual workspace ID.
    curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    Headers

    Authorization string (Required)

    Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
    URL path parameters

    task_id string (Required)

    The ID of the task.

    Response parameters

    Task successful

    Video URLs are valid 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 FAILED with an error code and message. See Error codes.

    {
    "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 return the following error.

    {
    "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 task ID. Valid for queries for 24 hours.

    task_status string

    The status of the task.

    Enumeration values

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: The task does not exist or its status is unknown.

    State transitions during polling:

    • PENDING → RUNNING → SUCCEEDED or FAILED.

    • The initial query status is usually PENDING or RUNNING.

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

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

    submit_time string

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

    scheduled_time string

    The time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

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

    video_url string

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

    Valid for 24 hours. The video is in MP4 format with H.264 encoding.

    code string

    Error code. Returned only for failed requests. See Error codes.

    message string

    Detailed error message. Returned only for failed requests. See Error codes.

    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 request identifier for tracing and troubleshooting.

    Billing and rate limiting

    Error codes

    If a model call fails, see Error codes 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