EMO 视频生成 API参考

EMO模型可基于人物肖像图片和人声音频,生成人脸动态视频。

重要

本文档仅适用于“中国大陆(北京)”地域,需使用“中国大陆(北京)”地域的API Key

效果示例

输入示例

输出示例

人物肖像:

上春山

人声音频:

使用动作风格强度:参数 style_level 设置为 'active'

更多效果示例请参见模型效果示例

说明

请确保上传的图片、音频文件来源符合相关法律法规,且已获得相应内容的使用许可。

前提条件

HTTP调用

步骤1:创建任务获取任务ID

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis
说明
  • 创建任务后,系统将立即返回一个 task_id,用于“步骤2”查询任务结果。task_id 自创建起有效期为24小时

  • 新手指引请参见Postman

请求参数

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "emo-v1",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/yhdvfg/emo-%E5%9B%BE%E7%89%87.png",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250825/aejgyj/input_audio.mp3",
        "face_bbox":[302,286,610,593],
        "ext_bbox":[71,9,840,778]
        },
    "parameters": {
        "style_level": "normal"
        }
    }'
import requests
import os

# 1. 从环境变量获取 API Key
api_key = os.getenv("DASHSCOPE_API_KEY")

# 2. 准备请求信息
url = 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis'

headers = {
    'X-DashScope-Async': 'enable',
    'Authorization': f'Bearer {api_key}',
}

payload = {
    "model": "emo-v1",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/yhdvfg/emo-%E5%9B%BE%E7%89%87.png",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250825/aejgyj/input_audio.mp3",
        "face_bbox": [302, 286, 610, 593],
        "ext_bbox": [71, 9, 840, 778]
    },
    "parameters": {
        "style_level": "normal"
    }
}

# 3. 发送 POST 请求
#    使用 'json' 参数,requests会自动处理JSON序列化和'Content-Type'头
response = requests.post(url, headers=headers, json=payload)

# 4. 打印服务器返回的原始JSON响应
#    如果请求成功,会打印任务ID等信息。
#    如果请求失败,会打印服务器返回的错误信息。
print(response.json())
请求头(Headers)

X-DashScope-Async string (必选)

异步处理配置参数。HTTP请求只支持异步,必须设置为enable

重要

缺少此请求头将报错:“current user api does not support synchronous calls”。

Authorization string(必选)

请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。

Content-Type string (必选)

请求内容类型。此参数必须设置为application/json

请求体(Request Body)

model string (必选)

模型名称。示例值:emo-v1。

说明

若调用独立部署模型,则填入部署成功的模型名称

input object (必选)

输入的基本信息。

属性

image_url string (必选)

用户上传的图片 URL。模型将根据EMO图像检测API返回的 ext_bbox 参数,对原始图片进行裁剪。裁剪后区域的宽高比直接决定了输出视频的画幅比例与分辨率。

  • 若 ext_bbox 宽高比为1:1,则生成512×512的头像视频;若为3:4,则生成512×704的半身像视频。

  • 图像要求最小边长 ≥ 400像素,最大边长 ≤ 7000像素。

  • 格式支持:jpg,jpeg,png,bmp,webp。

  • 示例值:https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/yhdvfg/emo-%E5%9B%BE%E7%89%87.png。

  • 上传文件支持HTTPHTTPS链接方式,不支持本地链接方式。您也可在此获取临时公网URL

audio_url string (必选)

用户上传的音频文件 URL, 用于EMO模型推理的输入。

  • 需包含清晰人声,并尽可能去除环境噪音、背景音乐等干扰。

  • 文件大小 ≤ 15 MB,时长 ≤ 60 s。

  • 格式支持:wav、mp3。

  • 示例值:https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250825/aejgyj/input_audio.mp3。

  • 上传文件支持HTTPHTTPS链接方式,不支持本地链接方式。您也可在此获取临时公网URL

face_bbox array (必选)

图片中人脸区域bbox的像素坐标,应输入EMO图像检测API出参中同名字段的值。坐标格式[x1,y1,x2,y2],分别对应左上和右下两个点的坐标。示例值:[302,286,610,593]。

图像左上角为坐标原点(0,0),x轴向右为正,y轴向下为正。

ext_bbox array (必选)

图片中动态区域bbox的像素坐标,应输入EMO图像检测API出参中同名字段的值。该区域的宽高比为1:13:4。坐标格式[x1,y1,x2,y2],分别对应左上和右下两个点的坐标。示例值:[71,9,840,778]。

parameters object(可选)

属性

style_level string (可选)默认值:normal

可选择动作风格强度控制人物的运动姿态和幅度,当前支持3种:normal、calm、active,分别对应人物动作风格适中、平静、活泼。默认为normal。

响应参数

响应成功示例

{
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-xxxxxx", 
        "task_status": "PENDING"
    },
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

响应异常示例

{
    "request_id":"4d687387-580a-4b49-a1f8-4691289e09a3",
    "code":"InvalidParameter",
    "message":"The request is missing required parameters or in a wrong format, please check the parameters that you send.."
}

output object

任务输出信息。

属性

task_id string

提交异步任务的任务ID,实际任务结果需要通过异步任务查询接口获取。示例值:a8532587-fa8c-4ef8-82be-xxxxxx。

task_status string

提交异步任务后的任务状态。示例值:“PENDING”。

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

code string

请求失败时返回的错误码,详情请参见状态码说明

message string

请求失败时返回的详细错误信息,详情请参见状态码说明

步骤2:根据任务ID查询结果

使用上一步获取的 task_id,轮询任务状态和结果。请将 URL 中的{task_id} 替换为您的实际任务ID。

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
说明
  • task_id 有效期:自创建起有效期24小时,超时后将无法查询结果,接口将返回任务状态为UNKNOWN

  • 任务状态流转:一般正常处理的任务流转状态为 PENDING(排队中)→ RUNNING(处理中)→ SUCCEEDED(成功)/ FAILED(失败)。

  • 任务结果获取:视频生成过程约需数分钟,查询接口默认QPS20。建议配置异步任务回调获取结果,或者采用轮询方式并设置合理的查询间隔(如 15 秒)来获取结果。

  • video_url 有效期:自任务成功时刻起有效期为 24 小时。建议在获取链接后立即下载并转存至永久存储(如阿里云 OSS)。

  • 更多操作:如需批量查询、取消任务等操作,请参见管理异步任务

请求参数

curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
import requests
import os

# 1. 从环境变量获取 API Key
api_key = os.getenv("DASHSCOPE_API_KEY")

# 2. 请替换为您真实需要查询的任务 ID
task_id = "a8532587-fa8c-4ef8-82be-xxxxxx"

# 3. 准备请求信息
# 使用 f-string 将 task_id 拼接到 URL 中
url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"

headers = {
    'Authorization': f'Bearer {api_key}'
}

# 4. 发送 GET 请求
response = requests.get(url, headers=headers)

# 5. 打印服务器返回的 JSON 响应
# 这将显示任务的状态(如 "RUNNING", "SUCCEEDED", "FAILED")和结果
print(response.json())

请求头(Headers)

Authorization string(必选)

请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。

URL路径参数(Path parameters)

task_id string (必选)

需要查询任务的task_id。示例值:a8532587-fa8c-4ef8-82be-xxxxxx。

响应参数

响应成功示例

{
    "request_id": "8190395f-ca1b-4703-9656-xxxxxx",
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-11 14:33:38.716",
        "scheduled_time": "2025-09-11 14:33:53.089",
        "end_time": "2025-09-11 14:35:51.541",
        "results": {
            "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxxx"
        }
    },
    "usage": {
        "video_duration": 13.93,
        "video_ratio": "1:1"
    }
}

响应异常示例

{
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-xxxxxx", 
        "task_status": "FAILED",
        "code": "InvalidURL", 
        "message": "Required URL is missing or invalid, please check the request URL." 
    },
    "request_id": "4d687387-580a-4b49-a1f8-4691289e09a3" 
}

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

output object

任务输出信息。

属性

task_id string

查询任务的 task_id。示例值:a8532587-fa8c-4ef8-82be-xxxxxx。

task_status string

任务状态。

枚举值

  • PENDING:任务排队中

  • RUNNING:任务处理中

  • SUCCEEDED:任务执行成功

  • FAILED:任务执行失败

  • CANCELED:任务已取消

  • UNKNOWN:任务不存在或状态未知

submit_time string

任务提交时间,时区为UTC+8,示例值:2025-09-11 14:33:38.716。

scheduled_time string

任务被安排计划开始执行的时间,时区为UTC+8,示例值:2025-09-11 14:33:53.089。

end_time string

任务执行结束时间,时区为UTC+8,示例值:2025-09-11 14:35:51.541。

results object

任务执行结果。

属性

video_url string

平台输出的视频结果,video_url有效期为任务完成后24小时,请及时下载并保存视频文件。示例值:http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxxx。

code string

请求失败时返回的错误码,详情请参见状态码说明

message string

请求失败时返回的详细错误信息,详情请参见状态码说明

usage object

属性

video_duration float

本次请求生成视频时长,单位:秒,示例值:13.93。

video_ratio string

本次请求生成视频的画幅比例,该值为1:13:4。

计费与限流

模式

模型名称

单价

免费额度(查看)

任务下发接口QPS限制

同时处理中任务数量

调用百炼模型API

emo-v1

后付费,按照输出视频的实际时长计费:

  • 生成1:1画幅比例视频:0.08元/秒

  • 生成3:4画幅比例视频:0.16元/秒

1800

5

1

(超出任务将排队)

独立部署模型

独立部署成功后将生成唯一的模型名称

预付费:

  • 10000元/算力单元/月

  • 20元/算力单元/小时

需部署成功后调用,仅收取部署费用。

5

1算力单元支持1并发

状态码说明

大模型服务平台通用状态码请查阅:错误信息

本模型还有如下特定错误码:

HTTP返回码

错误码(code)

错误信息(message)

含义说明

400

InvalidParameter

The request is missing required parameters or in a wrong format, please check the parameters that you send.

入参格式不对。

400

InvalidParameter

The style_level is invalid.

style_level不在枚举范围内。

400

InvalidParameter.DataInspection

Unable to download the media resource during the data inspection process. 

下载图片或音频文件超时。

如果您从海外发起调用,由于跨境网络不稳定,可能会导致下载资源超时。您可以将文件存储到国内的 OSS 中,再发起模型调用。您也可以使用临时存储空间上传文件。

400

InvalidURL

The request URL is invalid, please check the request URL is available and the request image format is one of the following types: JPEG, JPG, PNG, BMP, and WEBP.

输入图片下载失败,请检查网络或者输入格式。支持以下格式:JPEG, JPG, PNG, BMP, and WEBP。

400

InvalidURL

Required URL is missing or invalid, please check the request URL.

输入的URL不正确或缺失。

400

InvalidURL

The input audio is longer than 60s!

输入的音频文件超过最大时长60秒。

400

InvalidURL

File size is larger than 15MB.

输入的音频文件超过最大限制15MB。

400

InvalidURL

File type is not supported. Allowed types are: .wav, .mp3.

输入的音频格式不合规,当前支持wav、mp3。

400

InvalidFile.Content

The input image has no human body. Please upload other image with single person.

输入图片中没有人。请输入包含人物的图片。

400

InvalidFile.Content

The input image has multi human bodies. Please upload other image with single person.

输入图片中有多人。请输入只包含单个人的图片。

400

InvalidFile.BodyProportion

The proportion of the detected person in the picture is too large or too small, please upload other image.

输入图片中人物占比不符合要求。

400

InvalidFile.Resolution

The image resolution is invalid, please make sure that the largest length of image is smaller than 7000, and the smallest length of image is larger than 400.

图像分辨率无效。图像要求最小边长≥400像素,最大边长≤7000像素。

400

InvalidFile.Value

The value of the image is invalid, please upload other clearer image.

输入图片过暗不符合要求。请输入更清晰的图片。

400

InvalidFile.FrontBody

The pose of the detected person is invalid, please upload other image with the front view.

上传图片中人物背身不符合要求。请上传人物正面视角的图片。

400

InvalidFile.FullFace

The pose of the detected face is invalid, please upload other image with whole face.

上传图片中人物面部姿态不符合要求,请输入面部可见的图片。

400

InvalidFile.FacePose

The pose of the detected face is invalid, please upload other image with the expected orientation.

上传图片中人物面部姿态不符合要求,请输入面部朝向无严重偏移的图片。