全部产品
Search

搜索本产品

    大模型服务平台百炼：万相-视频换人API参考

    文档中心

    大模型服务平台百炼：万相-视频换人API参考

    更新时间：Mar 03, 2026

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

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

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

    效果示例

    万相-视频换人模型wan2.2-animate-mix提供标准模式wan-std和专业模式wan-pro两种服务模式，不同模式在效果和计费上存在差异，详情参见计费与限流。

    人物图片

    参考视频

    输出视频（标准模式wan-std）

    输出视频（专业模式wan-pro）

    mix_input_image

    HTTP调用

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

    重要

    北京和新加坡地域拥有独立的 API Key 与请求地址，不可混用，跨地域调用将导致鉴权失败或服务报错。

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

    1. 创建任务获取任务ID：发送一个请求创建任务，该请求会返回任务ID（task_id）。

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

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

    新加坡地域：POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

    北京地域：POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

    说明

    • 创建成功后，使用接口返回的 task_id 查询结果，task_id 有效期为 24 小时。请勿重复创建任务，轮询获取即可。

    • 新手指引请参见Postman。

    请求参数

    视频换人

    以下为新加坡地域base_url，若使用北京地域的模型，需将base_url替换为：https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

    curl --location 'https://dashscope-intl.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",
        "watermark": true
    },
    "parameters": {
        "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链接，不能包含中文等非ASCII字符，否则需要进行编码后再传入。

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

    • 尺寸限制：图像的宽度和高度都在[200,4096]像素范围内，宽高比在1:3至3: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链接，不能包含中文等非ASCII字符，否则需要进行编码后再传入。

    建议：提高参考视频的分辨率和帧率，可有效提升生成视频的画质效果。

    • 格式限制：MP4、AVI、MOV

    • 尺寸限制：视频的宽度和高度都在[200, 2048]像素范围内，宽高比在1:3至3:1范围内。

    • 大小限制：不超过200MB

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

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

    watermark bool （可选）

    是否添加水印标识，水印位于图片右下角，文案为“通义AI生成”。

    • false（默认值）：不添加水印。

    • true：添加水印。

    parameters object （必选）

    属性

    check_image bool （可选）

    是否进行图像检测。

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

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

    mode string （必选）

    模型服务模式选择，支持两种模式。

    • wan-std：标准模式，生成速度较快，性价比高，适用于快速预览和基础动画场景。

    • wan-pro：专业模式，动画流畅度更高，效果更佳，但处理时间和费用也相应增加。

    详情请参见效果示例和计费与限流。

    响应参数

    成功响应

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

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

    异常响应

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

    {
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-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-intl.aliyuncs.com/api/v1/tasks/{task_id}

    北京地域：GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

    说明

    • 轮询建议：视频生成过程约需数分钟，建议采用轮询机制，并设置合理的查询间隔（如 15 秒）来获取结果。

    • 任务状态流转：PENDING（排队中）→ RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。

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

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

    请求参数

    查询任务结果

    请将0385dc79-5ff8-4d82-bcb6-xxxxxx替换为真实的task_id。

    以下为新加坡地域base_url ，若使用北京地域的模型，需将base_url替换为：https://dashscope.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx
    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-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": "0385dc79-5ff8-4d82-bcb6-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

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

    scheduled_time string

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

    end_time string

    任务完成时间。时区为UTC+8，格式为 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

    本次请求视频服务模式选择，枚举值： standard，pro。

    若选择标准模式wan-std为standard，选择专业模式wan-pro则为pro。

    request_id string

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

    使用限制

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

    内容审核：输入与输出内容均会经过内容安全审核，包含违规内容的请求将报错“IPInfringementSuspect”或“DataInspectionFailed”，具体参见错误信息。

    计费与限流

    • 模型免费额度和计费单价请参见模型价格。

    • 模型限流请参见万相系列。

    • 计费说明：

      • 输入不计费，输出计费。按成功生成的 视频秒数 计费。

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

    错误码

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

    常见问题

    Q: 如何查看模型调用量？

    A: 模型的调用信息存在小时级延迟，在模型调用完约一小时后，请在模型观测（新加坡或北京）页面，查看调用量、调用次数、成功率等指标。如何查看模型调用记录？

    Q: 如何优化生成视频的效果?

    A: 可参考以下建议

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

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

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

    Q: 如何将临时的视频链接转为永久链接？

    A: 不能直接转换该链接。正确的做法是：后端服务获取到url后，通过代码下载该视频文件，然后将其上传到永久对象存储服务（如阿里云 OSS），生成一个新的、永久访问链接。

    示例代码：下载视频到本地

    import requests

def download_and_save_video(video_url, save_path):
    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}")

if __name__ == '__main__':
    video_url = "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx"
    save_path = "video.mp4"
    download_and_save_video(video_url, save_path)

    Q: 返回的视频链接可以在浏览器中直接播放吗？

    A: 不建议这样做，因为链接会在 24 小时后失效。最佳实践是后端下载转存后，使用永久链接进行视频播放。

    Q：如何获取视频存储的访问域名白名单？

    A： 模型生成的视频存储于阿里云OSS，API将返回一个临时的公网URL。若需要对该下载地址进行防火墙白名单配置，请注意：由于底层存储会根据业务情况进行动态变更，为避免过期信息影响访问，文档不提供固定的OSS域名白名单。如有安全管控需求，请联系客户经理获取最新OSS域名列表。