Emoji video generation API reference - Alibaba Cloud Model Studio

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

Obtain an API key and export the API key as an environment variable.
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

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.

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.

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]
    }
}'

Response parameters

output objectTask status and results.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

Successful response
Error 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"
}

Step 2: Query the result by task ID

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

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_idvalidity: 24 hours. After this period, queries return the task status as UNKNOWN.

Request parameters

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.

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"

Response parameters

outputobjectTask status and results.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe 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 stringThe 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 stringThe 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 stringThe 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 stringURL 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 stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

usage objectOutput usage statistics (successful tasks only).

Properties

video_duration integerThe duration of the generated video in seconds.

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

video_ratio stringVideo aspect ratio. Fixed at standard (1:1).

request_id stringUnique request identifier for tracing and troubleshooting.

Task successful
Task failed
Task query expired

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

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

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

Billing and rate limiting

For the free quota and unit price, see Recommended models.
For the rate limits, see 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" } }.

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		dagong_zhuakuang
mengwa_dengyan		dagong_wunai
mengwa_gandong		dagong_weixiao
mengwa_renzhen_1		dagong_ganji
mengwa_jidong		jingdian_tiaopi
mengwa_kun_1		jingdian_deyi_1
mengwa_jiaoxie		jingdian_qidai
dagong_kaixin		jingdian_landuo_1
dagong_yangwang		jingdian_xianqi
dagong_kunhuo		jingdian_lei