通义万相-视频换人API参考

通义万相wan2.2-animate-mix视频换人模型,能够依据人物图片和参考视频,将视频中的主角替换为图片中的角色,同时保留原视频的场景、光照和色调,实现无缝换人。

  • 核心功能: 在不改变原始视频的动作、表情及环境的条件下,将视频中的角色替换为指定图片中的人物。

    适用场景:适用于二次创作、影视后期制作等需要进行角色替换的场景。

模型概览

效果示例

人物图片

参考视频

输出视频(视频换人-标准std)

输出视频(视频换人-专业pro)

mix_input_image

模型与价格

wan2.2-animate-mix 模型提供标准和专业两种服务模式,以满足不同场景对视频换人效果的需求。

模型名称

模型服务

服务简介

限流(主账号与RAM子账号共用)

计费单价

免费额度(查看)

任务下发接口RPS限制

同时处理中任务数量

wan2.2-animate-mix

视频换人-标准std

生成速度快,满足基础动画演示等轻需求,性价比高。

5

1

0.6元/秒

两种服务共50

视频换人-专业pro

动画流畅度高,动作表情过渡自然,效果更接近真实拍摄。

0.9元/秒

HTTP调用

您需要已获取API Key配置API Key到环境变量

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/

由于视频生成耗时较长,HTTP API 采用异步模式,调用流程分两步:

  1. 创建任务获取任务ID:发送一个请求创建任务,该请求会返回任务ID(task_id)

  2. 根据任务ID查询结果:使用task_id轮询任务状态,直到任务完成并获得视频URL。

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

说明
  • 创建成功后,使用接口返回的 task_id 查询结果,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": "wan2.2-animate-mix",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg",
        "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4"
    },
    "parameters": {
        "check_image": true,
        "mode": "wan-std"
    }
  }'

请求头(Headers)

Content-Type string (必选)

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

Authorization string(必选)

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

X-DashScope-Async string (必选)

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

重要

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

请求体(Request Body)

model string (必选)

模型名称,必须设置为wan2.2-animate-mix

input object (必选)

输入参数对象,包含以下字段:

属性

image_url string (必选)

输入图像的公网可访问的HTTP/HTTPS链接,不能包含中文字符。

本地文件可通过上传文件获取临时URL

  • 格式限制:JPG、JPEG、PNG、BMP、WEBP

  • 尺寸限制:图像的宽度和高度各自都必须在[200,4096]像素范围内,宽高比在1:33:1范围内。

  • 大小限制:不超过5MB

  • 示例https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg

video_url string (必选)

输入视频的公网可访问的HTTP/HTTPS链接,不能包含中文字符。

本地文件可通过上传文件获取临时URL

建议:提高模板视频的分辨率和帧率,可有效提升生成视频的画质效果。

  • 格式限制:MP4、AVI、MOV

  • 尺寸限制:宽高200-2048像素,宽高比1:33:1

  • 大小限制:不超过200MB

  • 时长限制:不小于2s且不大于30s

  • 示例https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4

parameters object (必选)

属性

check_image bool (可选)

是否进行图像检测。

  • true默认值,接口将对传入的图片进行检测。

  • false:跳过图片检测环节,直接对图片进行后续处理。

mode string (必选)

模型服务模式选择,支持标准模型std和专业模式pro两种模式。

  • wan-std:采用图生动作-标准std服务,生成标准模型的视频。

  • wan-pro:采用图生动作-专业pro服务,生成专业模型的视频。

计费说明: wan-pro 模式效果更佳,但计费单价高于 wan-std 模式。请根据业务需求选择。

响应参数

成功响应

请保存 task_id,用于查询任务状态与结果。

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

异常响应

创建任务失败,请参见错误信息进行解决。

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxx"
}

output object

任务输出信息。

属性

task_id string

任务ID。查询有效期24小时。

task_status string

任务状态。

枚举值

  • PENDING:任务排队中

  • RUNNING:任务处理中

  • SUCCEEDED:任务执行成功

  • FAILED:任务执行失败

  • CANCELED:任务已取消

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

request_id string

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

message string

请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误信息

code string

请求失败的错误码。请求成功时不会返回此参数,详情请参见错误信息

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

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

说明
  • 轮询建议:视频生成过程约需数分钟,建议采用轮询机制,并设置合理的查询间隔(如 15 秒)来获取结果。

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

  • 结果链接:任务成功后返回视频链接,有效期为 24 小时。建议在获取链接后立即下载并转存至永久存储(如阿里云 OSS)。

  • task_id 有效期24小时,超时后将无法查询结果,接口将返回任务状态为UNKNOWN

  • QPS 限制:查询接口默认QPS20。如需更高频查询或实时通知,建议配置配置异步任务回调

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

请求参数

查询任务结果

您需要将d279369d-97d5-40ad-a30d-xxxxxx替换为真实的task_id。

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/d279369d-97d5-40ad-a30d-xxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
请求头(Headers)

Authorization string(必选)

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

URL路径参数(Path parameters)

task_id string(必选)

任务ID。

响应参数

任务执行成功

视频URL仅保留24小时,超时后会被自动清除,请及时保存生成的视频。

{
    "request_id": "a67f8716-18ef-447c-a286-xxxxxx",
    "output": {
        "task_id": "d279369d-97d5-40ad-a30d-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-18 15:32:00.105",
        "scheduled_time": "2025-09-18 15:32:15.066",
        "end_time": "2025-09-18 15:34:41.898",
        "results": {
            "video_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx"
        }
    },
    "usage": {
        "video_duration": 5.2,
        "video_ratio": "standard"
    }
}

任务执行失败

若任务执行失败,task_status将置为 FAILED,并提供错误码和信息。请参见错误信息进行解决。

{
    "request_id": "daad9007-6acd-9fb3-a6bc-xxxxxx",
    "output": {
        "task_id": "fe8aa114-d9f1-4f76-b598-xxxxxx",
        "task_status": "FAILED",
        "code": "InternalError",
        "message": "xxxxxx"
    }
}

output object

任务输出信息。

属性

task_id string

任务ID。查询有效期24小时。

task_status string

任务状态。

枚举值

  • PENDING:任务排队中

  • RUNNING:任务处理中

  • SUCCEEDED:任务执行成功

  • FAILED:任务执行失败

  • CANCELED:任务已取消

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

submit_time string

任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。

scheduled_time string

任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。

end_time string

任务完成时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。

results object

属性

video_url string

视频URL。仅在 task_status 为 SUCCEEDED 时返回。

链接有效期24小时,可通过此URL下载视频。视频格式为MP4(H.264 编码)。

code string

请求失败的错误码。请求成功时不会返回此参数,详情请参见错误信息

message string

请求失败的详细信息。请求成功时该参数为空,详情请参见错误信息

usage object

输出信息统计。只对成功的结果计数。

属性

video_duration float

本次请求生成视频时长计量,单位:秒。

video_ratio string

本次请求视频服务模式选择,枚举值: standardpro

若选择标准模式wan-stdstandard,专业模式wan-pro则为pro

request_id string

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

使用限制与建议

使用限制

  • 输入内容限制:以下是输入图片与视频的内容限制,对于视频,相关要求适用于首帧

    • 人数:必须仅包含一个人,不能无人或多人。

    • 清晰度:必须清晰,特别是人脸部分,不能过暗或模糊。

    • 完整性:人脸必须 完整无遮挡。

    • 朝向:人物需要正面朝向镜头,不能是背身。人脸朝向应基本正对,不能有严重偏斜。

    • 构图:人物在图片中的占比要适中,不能过大(如大头贴)或过小。

    除此之外,输入图片视频还需要满足格式、尺寸、大小等限制。

  • 内容审核:输入的图片与视频均会经过内容安全审核,包含违规内容的请求将报错“IPInfringementSuspect”或“DataInspectionFailed”,具体参见错误信息

  • 数据时效:任务task_id和视频URL均只保留 24 小时,过期后将无法查询或下载,请及时下载视频到本地

使用建议

为了优化视频换人效果,请参考以下建议::

  1. 确保输入图片与参考视频中的人物画幅占比相似。

  2. 尽量保持图片和视频中人物的身材比例一致。

  3. 使用高清素材,避免使用模糊图片和低帧率视频,确保细节识别准确。

下载视频到本地

import requests

video_url = "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx?Expires=xxx"
save_path = "ouput_video.mp4"
try:
    response = requests.get(video_url, stream=True, timeout=300) # 设置超时
    response.raise_for_status() # 如果HTTP状态码不是200,则引发异常
    with open(save_path, 'wb') as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)
    print(f"视频已成功下载到: {save_path}")

except requests.exceptions.RequestException as e:
    print(f"视频下载失败: {e}")
import java.io.FileOutputStream;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class ImageDownloader {
    public static void downloadImage(String videoUrl, String savePath) {
        try {
            // 创建 URL 对象
            URL url = new URL(videoUrl);
            // 打开连接
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            // 设置超时时间
            connection.setConnectTimeout(5000);
            connection.setReadTimeout(300000); // 5分钟
            // 设置请求方法
            connection.setRequestMethod("GET");

            // 获取输入流
            InputStream inputStream = connection.getInputStream();
            // 创建文件输出流
            FileOutputStream outputStream = new FileOutputStream(savePath);

            // 缓冲区
            byte[] buffer = new byte[8192];
            int bytesRead;

            // 写入文件
            while ((bytesRead = inputStream.read(buffer)) != -1) {
                outputStream.write(buffer, 0, bytesRead);
            }

            // 关闭流
            inputStream.close();
            outputStream.close();

            System.out.println("视频已成功下载到: " + savePath);
        } catch (Exception e) {
            System.err.println("视频下载失败: " + e.getMessage());
        }
    }

    public static void main(String[] args) {
        String videoUrl = "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx?Expires=xxx";
        String savePath = "output_video.mp4";
        downloadImage(videoUrl, savePath);
    }
}

计费与限流

计费规则

  • 计费项:按成功生成的 视频秒数 计费,采用按量后付费模式。

  • 计费公式:费用 = 计费单价 × 视频时长(秒)

  • 抵扣顺序:优先消耗免费额度。额度用尽后,默认转为按量付费。

    • 您可开启“免费额度用完即停”功能,以避免免费额度耗尽后产生额外费用。详情请参见免费额度

  • 失败不计费:模型调用失败或处理错误不产生任何费用,也不消耗免费额度。

免费额度

关于免费额度的领取、查询、使用方法等详情,请参见免费额度

调用量查询

模型调用完约一小时后,请在模型观测页面,查看调用量、调用次数、成功率等指标。

限流

模型限流规则及常见问题,请参见限流

错误码

如果模型调用失败并返回报错信息,请参见错误信息进行解决。