Vidu-图像生成API参考 - 阿里云百炼

本文档仅适用于华北2（北京）地域，且必须使用该地域的API Key。

模型概览

模型名称	能力支持	输入模态	输出图像规格
vidu/vidu-image_reference2image vidu/vidu-image-pro_reference2image vidu/vidu-image-lite_reference2image	支持参考生图、文生图、图片编辑，对中英文字的精准渲染、UI/图表等设计细节的像素级还原，适合制作海报、信息图等。	文本、图像	图像分辨率：1K、2K、4K 图像张数：1 图像格式：PNG
vidu/viduq3-fast_reference2image	支持参考生图、文生图、图片编辑，主打高速高质与低成本，成本比Pro降低约50%。	文本、图像	图像分辨率：1K、2K、4K 图像张数：1 图像格式：PNG
vidu/viduq2-pro_reference2image	支持参考生图、文生图、图片编辑，擅长处理复杂逻辑，具备超强上下文一致性和工业级稳定性。适合专业设计、漫剧制作等。	文本、图像	图像分辨率：1K、2K、4K 图像张数：1 图像格式：PNG
vidu/viduq2-fast_reference2image	支持参考生图、文生图、图片编辑，语义理解能力大幅提升，支持更多风格。	文本、图像	图像分辨率：1K 图像张数：1 图像格式：PNG

前提条件

开通服务：前往阿里云百炼控制台，搜索"Vidu"，找到对应模型卡片，单击立即开通，在弹窗内确认开通及授权。
配置API Key：选择地域并获取与配置 API Key。

HTTP调用

图像生成任务有一定耗时，API采用异步调用。整个流程包含 "创建任务 -> 轮询获取" 两个核心步骤，具体如下：

步骤一：提交图像生成任务

北京地域：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation 调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求参数

请求头（Headers）

Content-Typestring（必选）请求内容类型。此参数必须设置为application/json。Authorizationstring（必选）请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值：Bearer sk-xxxx。X-DashScope-Asyncstring（必选）异步处理配置参数。HTTP请求只支持异步，必须设置为enable。

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

请求体（Request Body）

model string （必选）模型名称。可选值：

vidu/vidu-image_reference2image
vidu/vidu-image-pro_reference2image
vidu/vidu-image-lite_reference2image
vidu/viduq3-fast_reference2image
vidu/viduq2-pro_reference2image
vidu/viduq2-fast_reference2image

input object （必选）输入参数对象，包含以下字段：

属性

messages array （必选）多轮消息列表。服务端会提取第一个非空text作为提示词，并提取全部image作为参考图。数组内有且只有一个对象，该对象包含role和content两个属性。

属性

rolestring （可选）消息的角色，建议设置为user。contentarray （必选）消息内容，包含文本提示词（text）和可选的参考图像（image，支持多张）。

属性

textstring（条件必选）正向提示词，用于描述期望生成的图像内容、风格和构图。支持中英文，长度不超过5000个字符，每个汉字、字母、数字或符号计为一个字符。示例值：一只坐着的橘黄色的猫，表情愉悦，活泼可爱，逼真准确。注意：整个messages中至少需要一个非空文本。image string （可选）参考图像的URL。支持传多张，所有模型最多支持输入14张。

支持 HTTP 或 HTTPS 协议。
示例值：https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png。

图像限制：

格式：PNG、JPG、WEBP。
宽高比：在1:4 ~ 4:1之间。
文件大小：所有图片总和不超过50MB。
数量限制：最多14张参考图片。

parameters object （可选）控制图像生成参数。

属性

size string （可选）图片尺寸，格式为宽*高（如2048*2048）。不传时默认1024*1024。不同模型支持的尺寸列表请参见下方可用尺寸列表。n integer （可选）生成图片数量，当前仅支持1。传其他值会返回参数错误。seed integer （可选）随机数种子，取值范围[0,2147483647]，0表示随机。使用相同的seed参数值可使生成内容保持相对稳定。若不提供，算法将自动使用随机数种子。watermark bool （可选）是否添加水印标识。

false：默认值，不添加水印。
true：添加水印。

文生图
参考图生图

支持所有Vidu模型。

# 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "vidu/vidu-image_reference2image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1,
        "watermark": false
    }
}'

支持所有Vidu模型，最多可传入14张参考图。

# 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "vidu/vidu-image_reference2image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "参考图片的风格，生成一只坐着的橘黄色的猫"
                    },
                    {
                        "image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "size": "2048*2048",
        "n": 1,
        "watermark": false
    }
}'

响应参数

request_idstring请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数，详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误码。

成功响应
异常响应

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

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

步骤二：查询任务结果

北京地域：GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} 调用时请将{WorkspaceId}替换为真实的业务空间ID。

轮询建议：图像生成过程需一定时间，建议采用轮询机制，并设置合理的查询间隔（如5秒）来获取结果。
任务状态流转：PENDING（等待中）→ RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。
图片链接有效期：生成图像的下载链接24小时内有效，请及时下载并保存图像。

请求参数

请求头（Headers）

Authorizationstring（必选）请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值：Bearer sk-xxxx。task_id string（必选）任务ID。

查询任务结果

# 以下为华北2（北京）地域的URL，调用时请将 {WorkspaceId} 替换为真实的业务空间ID，各地域的URL不同。
curl --location --request GET 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

响应参数

output object任务输出信息。

属性

task_id string任务ID。choices array图片输出候选列表，仅在task_status=SUCCEEDED时返回。

属性

finish_reason string结束原因，成功时通常为stop。message object模型返回的消息。

属性

rolestring消息的角色，固定为assistant。contentarray

属性

type string输出内容的类型，固定为image。image string生成图像的下载链接，图像格式为PNG。链接有效期为24小时，请及时下载并保存图像。

finished bool是否完成，仅在task_status=SUCCEEDED时返回。

usage object资源用量信息。只对成功的结果计数。

属性

image_count integer生成图像的数量。size string生成图片的分辨率，格式为宽*高。示例值：2048*2048。SR string生成图像的分辨率档位。示例值：2K。

任务执行成功
任务执行异常

{
    "request_id": "f584a817-6e00-9841-961a-49f7382a03d4",
    "output": {
        "task_id": "6404d4ec-4cdf-45b5-8d7d-3d429c6baed5",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-07-13 20:27:41.291",
        "scheduled_time": "2026-07-13 20:27:41.320",
        "end_time": "2026-07-13 20:28:39.767",
        "finished": true,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://example.com/generated-image.png",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "SR": "2K",
        "size": "2048*2048",
        "image_count": 1
    }
}

如果因为某种原因导致任务执行失败，将返回相关信息，可以通过code和message字段明确指示错误原因。请参见错误码进行解决。

{
    "request_id": "1f015514-b04c-9190-b4dd-8ba11bb15708",
    "output": {
        "task_id": "ccae6c03-fe9f-48fd-b3d6-a524c4707f17",
        "task_status": "FAILED",
        "submit_time": "2026-07-13 20:27:50.654",
        "scheduled_time": "2026-07-13 20:27:50.689",
        "end_time": "2026-07-13 20:27:51.090",
        "code": "InvalidParameter",
        "message": "Missing required field 'parameters.n' in request body"
    }
}

错误码

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

可用尺寸列表

vidu-image、vidu-image-pro、vidu-image-lite

分辨率	支持尺寸
1K	10241024、7201440、1440720、1024768、7681024、19201088、10881920、15361024、10241536、1920816、816*1920
2K	20482048、10882160、21601088、27362048、20482736、25601440、14402560、30722048、20483072、25601104、1104*2560
4K	28802880、14402880、28801440、33122480、24803312、38402160、21603840、35202352、23523520、38401648、1648*3840

viduq3-fast

分辨率	支持尺寸
1K	10241024、7681376、8481264、8961200、9281152、1152928、1200896、1264848、1376768、1584672、5122064、2064512、3522928、2928352
2K	20482048、15362752、16962528、17922400、18562304、23041856、24001792、25281696、27521536、31681344、10244128、41281024、7045856、5856704
4K	40964096、30725504、33925056、35844800、37124608、46083712、48003584、50563392、55043072、63362688、20488256、82562048、140811712、117121408

viduq2-pro

分辨率	支持尺寸
1K	10241024、7681376、8481264、8961200、9281152、1152928、1200896、1264848、1376768、1584672
2K	20482048、15362752、16962528、17922400、18562304、23041856、24001792、25281696、27521536、31681344
4K	40964096、30725504、33925056、35844800、37124608、46083712、48003584、50563392、55043072、63362688

viduq2-fast

分辨率	支持尺寸
1K	10241024、7681376、8481264、8961200、9281152、1152928、1200896、1264848、1376768、1584672

​模型概览

​前提条件

​HTTP调用

​步骤一：提交图像生成任务

请求参数

请求头（Headers）

请求体（Request Body）

响应参数

​步骤二：查询任务结果

请求参数

请求头（Headers）

响应参数

​错误码

​可用尺寸列表

​vidu-image、vidu-image-pro、vidu-image-lite

​viduq3-fast

​viduq2-pro

​viduq2-fast

模型概览

前提条件

HTTP调用

步骤一：提交图像生成任务

步骤二：查询任务结果

错误码

可用尺寸列表

vidu-image、vidu-image-pro、vidu-image-lite

viduq3-fast

viduq2-pro

viduq2-fast