Emoji-Emoji video generation API reference

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

Get 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

## Generate an Emoji video

curl

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.

<b>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.

json

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

json

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

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

<b>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.

json

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

json

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

json

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

<b>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

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

Emoji-Emoji video generation API reference ​

Model overview ​

Prerequisites ​

HTTP ​

Step 1: Create a task and get the task ID ​

Request parameters ​

## Generate an Emoji video ​

Headers ​

Request body ​

Response parameters ​

Successful response ​

Error response ​

Step 2: Query the result by task ID ​

Request parameters ​

## Query task results ​

<b>Headers** ​

URL path parameters ​

Response parameters ​

## Task successful ​

## Task failed ​

## Task query expired ​

Billing and rate limiting ​

Error codes ​

Appendix: List of template IDs ​

Emoji-Emoji video generation API reference

Model overview

Prerequisites

HTTP

Step 1: Create a task and get the task ID

Request parameters

## Generate an Emoji video

Headers

Request body

Response parameters

Successful response

Error response

Step 2: Query the result by task ID

Request parameters

## Query task results

<b>Headers**

URL path parameters

Response parameters

## Task successful

## Task failed

## Task query expired

Billing and rate limiting

Error codes

Appendix: List of template IDs