通义万相-文生图模型基于文本生成图像，支持多种艺术风格与写实摄影效果，满足多样化创意需求。
快速入口：通义万相官网在线体验 ｜ 文生图使用指南
说明
通义万相官网的功能与API支持的能力可能存在差异，具体以API文档中列出的能力为准。如有新增功能，API文档会及时更新，敬请关注。
模型概览
模型名称 | 模型简介 | 输出图像格式 |
wan2.5-t2i-preview | 万相2.5 preview 取消单边限制，在总像素面积与宽高比约束内，自由选尺寸 例如，支持768*2700，而2.2 及以下版本单边上限 1400 | 图像分辨率：总像素在[768*768, 1440*1440]之间 图像宽高比：[1:4, 4:1] |
wan2.2-t2i-flash | 万相2.2极速版 较2.1模型速度提升50% | 图像分辨率：宽高均在[512, 1440]像素之间 图像格式：png |
wan2.2-t2i-plus | 万相2.2专业版 较2.1模型稳定性与成功率全面提升 | |
wanx2.1-t2i-turbo | 万相2.1极速版 | |
wanx2.1-t2i-plus | 万相2.1专业版 | |
wanx2.0-t2i-turbo | 万相2.0极速版 |
说明
调用前，请查阅各地域支持的模型列表与价格。
前提条件
在调用前，先获取API Key，再配置API Key到环境变量。如需通过SDK进行调用，请安装DashScope SDK。
重要
北京和新加坡地域拥有独立的 API Key 与请求地址，不可混用，跨地域调用将导致鉴权失败或服务报错。
HTTP调用
由于文生图任务耗时较长（通常为1-2分钟），API采用异步调用。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤，具体如下：
具体耗时受限于排队任务数和服务执行情况，请在获取结果时耐心等待。
步骤1：创建任务获取任务ID
北京地域：POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
新加坡地域：POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
说明
创建成功后，使用接口返回的
task_id查询结果，task_id 有效期为 24 小时。请勿重复创建任务，轮询获取即可。新手指引请参见Postman。
请求参数 | 文生图文生图（使用反向提示词）通过 negative_prompt 指定生成的图片避免出现“人物”元素。 |
请求头（Headers） | |
Content-Type 请求内容类型。此参数必须设置为 | |
Authorization 请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值：Bearer sk-xxxx。 | |
X-DashScope-Async 异步处理配置参数。HTTP请求只支持异步，必须设置为 重要 缺少此请求头将报错：“current user api does not support synchronous calls”。 | |
请求体（Request Body） | |
model 模型名称。示例值：wan2.5-t2i-preview。 各模型信息详见模型列表与价格。 | |
input 输入的基本信息，如提示词等。 | |
parameters 图像处理参数。如设置图像分辨率、开启prompt智能改写、添加水印等。 |
响应参数 | 成功响应请保存 task_id，用于查询任务状态与结果。 异常响应创建任务失败，请参见错误信息进行解决。 |
output 任务输出信息。 | |
request_id 请求唯一标识。可用于请求明细溯源和问题排查。 | |
code 请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。 | |
message 请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。 |
步骤2：根据任务ID查询结果
北京地域：GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
新加坡地域：GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
请求参数 | 查询任务结果请将 |
请求头（Headers） | |
Authorization 请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值：Bearer sk-xxxx。 | |
URL路径参数（Path parameters） | |
task_id 任务ID。 |
响应参数 | 任务执行成功图像URL仅保留24小时，超时后会被自动清除，请及时保存生成的图像。 任务执行失败若任务执行失败，task_status将置为 FAILED，并提供错误码和信息。请参见错误信息进行解决。 任务部分失败模型可以在一次任务中生成多张图片。只要有一张图片生成成功，任务状态将标记为 任务查询过期task_id查询有效期为 24 小时，超时后将无法查询，返回以下报错信息。 |
output 任务输出信息。 | |
usage 输出信息统计。只对成功的结果计数。 | |
request_id 请求唯一标识。可用于请求明细溯源和问题排查。 |
DashScope SDK调用
SDK 的参数命名与HTTP接口基本一致，参数结构根据语言特性进行封装。
由于文生图任务耗时较长（通常为1-2分钟），SDK 在底层封装了 HTTP 异步调用流程，支持同步、异步两种调用方式。
具体耗时受限于排队任务数和服务执行情况，请在获取结果时耐心等待。
Python SDK调用
说明
推荐安装最新版DashScope Python SDK，否则可能运行报错：安装或升级SDK。
同步调用
请求示例
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
prompt = "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵"
# 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
# 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(api_key=api_key,
model="wan2.2-t2i-flash",
prompt=prompt,
n=1,
size='1024*1024')
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
# 在当前目录下保存图片
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('sync_call Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
响应示例
url 有效期24小时，请及时下载图像。
{
"status_code": 200,
"request_id": "9d634fda-5fe9-9968-a908-xxxxxx",
"code": null,
"message": "",
"output": {
"task_id": "d35658e4-483f-453b-b8dc-xxxxxx",
"task_status": "SUCCEEDED",
"results": [{
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png",
"orig_prompt": "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵",
"actual_prompt": "一间精致的花店，窗户上装饰着优雅的雕花，漂亮的木质门上挂着铜制把手。店内摆放着各种色彩鲜艳的花朵，如玫瑰、郁金香和百合等。背景是温馨的室内场景，光线柔和，营造出宁静舒适的氛围。高清写实摄影，近景中心构图。"
}],
"submit_time": "2025-01-08 19:36:01.521",
"scheduled_time": "2025-01-08 19:36:01.542",
"end_time": "2025-01-08 19:36:13.270",
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"image_count": 1
}
}
异步调用
请求示例
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
prompt = "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵"
# 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
# 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
def async_call():
print('----create task----')
task_info = create_async_task()
print('----wait task done then save image----')
wait_async_task(task_info)
# 创建异步任务
def create_async_task():
rsp = ImageSynthesis.async_call(api_key=api_key,
model="wan2.2-t2i-flash",
prompt=prompt,
n=1,
size='1024*1024')
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
return rsp
# 等待异步任务结束
def wait_async_task(task):
rsp = ImageSynthesis.wait(task)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
# 获取异步任务信息
def fetch_task_status(task):
status = ImageSynthesis.fetch(task)
print(status)
if status.status_code == HTTPStatus.OK:
print(status.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(status.status_code, status.code, status.message))
# 取消异步任务，只有处于PENDING状态的任务才可以取消
def cancel_task(task):
rsp = ImageSynthesis.cancel(task)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
async_call()
响应示例
1、创建任务的响应示例
{
"status_code": 200,
"request_id": "31b04171-011c-96bd-ac00-f0383b669cc7",
"code": "",
"message": "",
"output": {
"task_id": "4f90cf14-a34e-4eae-xxxxxxxx",
"task_status": "PENDING",
"results": []
},
"usage": null
}2、查询任务结果的响应示例
url 有效期24小时，请及时下载图像。
{
"status_code": 200,
"request_id": "9d634fda-5fe9-9968-a908-xxxxxx",
"code": null,
"message": "",
"output": {
"task_id": "d35658e4-483f-453b-b8dc-xxxxxx",
"task_status": "SUCCEEDED",
"results": [{
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png",
"orig_prompt": "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵",
"actual_prompt": "一间精致的花店，窗户上装饰着优雅的雕花，漂亮的木质门上挂着铜制把手。店内摆放着各种色彩鲜艳的花朵，如玫瑰、郁金香和百合等。背景是温馨的室内场景，光线柔和，营造出宁静舒适的氛围。高清写实摄影，近景中心构图。"
}],
"submit_time": "2025-01-08 19:36:01.521",
"scheduled_time": "2025-01-08 19:36:01.542",
"end_time": "2025-01-08 19:36:13.270",
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"image_count": 1
}
}
Java SDK调用
说明
推荐安装最新版DashScope Java SDK，否则可能运行报错：安装或升级SDK。
同步调用
请求示例
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
}
public static void basicCall() throws ApiException, NoApiKeyException {
String prompt = "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵";
// 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey="sk-xxx"
// 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
String apiKey = System.getenv("DASHSCOPE_API_KEY");
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.2-t2i-flash")
.prompt(prompt)
.n(1)
.size("1024*1024")
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageSynthesis.call(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void listTask() throws ApiException, NoApiKeyException {
ImageSynthesis is = new ImageSynthesis();
AsyncTaskListParam param = AsyncTaskListParam.builder().build();
ImageSynthesisListResult result = is.list(param);
System.out.println(result);
}
public void fetchTask() throws ApiException, NoApiKeyException {
String taskId = "your task id";
ImageSynthesis is = new ImageSynthesis();
// If set DASHSCOPE_API_KEY environment variable, apiKey can null.
ImageSynthesisResult result = is.fetch(taskId, null);
System.out.println(result.getOutput());
System.out.println(result.getUsage());
}
public static void main(String[] args){
try{
basicCall();
//listTask();
}catch(ApiException|NoApiKeyException e){
System.out.println(e.getMessage());
}
}
}响应示例
url 有效期24小时，请及时下载图像。
{
"request_id": "22f9c744-206c-9a78-899a-xxxxxx",
"output": {
"task_id": "4a0f8fc6-03fb-4c44-a13a-xxxxxx",
"task_status": "SUCCEEDED",
"results": [{
"orig_prompt": "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵",
"actual_prompt": "一间有着精致雕花窗户的花店，漂亮的深色木质门微微敞开。店内摆放着各式各样的鲜花，包括玫瑰、百合和向日葵，色彩鲜艳，香气扑鼻。背景是温馨的室内场景，光线柔和，透过窗户洒在花朵上。高清写实摄影，中景构图。",
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png"
}],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"image_count": 1
}
}异步调用
请求示例
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
}
public void asyncCall() {
System.out.println("---create task----");
String taskId = this.createAsyncTask();
System.out.println("---wait task done then return image url----");
this.waitAsyncTask(taskId);
}
/**
* 创建异步任务
* @return taskId
*/
public String createAsyncTask() {
String prompt = "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵";
// 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey="sk-xxx"
// 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
String apiKey = System.getenv("DASHSCOPE_API_KEY");
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.2-t2i-flash")
.prompt(prompt)
.n(1)
.size("1024*1024")
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
result = imageSynthesis.asyncCall(param);
} catch (Exception e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
return taskId;
}
/**
* 等待异步任务结束
* @param taskId 任务id
* */
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
//如果已经在环境变量中设置了 DASHSCOPE_API_KEY，wait()方法可将apiKey设置为null
result = imageSynthesis.wait(taskId, null);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
System.out.println(JsonUtils.toJson(result.getOutput()));
}
public static void main(String[] args){
Main main = new Main();
main.asyncCall();
}
}响应示例
1、创建任务的响应示例
{
"request_id": "5dbf9dc5-4f4c-9605-85ea-542f97709ba8",
"output": {
"task_id": "7277e20e-aa01-4709-xxxxxxxx",
"task_status": "PENDING"
}
}2、查询任务结果的响应示例
{
"request_id": "22f9c744-206c-9a78-899a-xxxxxx",
"output": {
"task_id": "4a0f8fc6-03fb-4c44-a13a-xxxxxx",
"task_status": "SUCCEEDED",
"results": [{
"orig_prompt": "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵",
"actual_prompt": "一间有着精致雕花窗户的花店，漂亮的深色木质门微微敞开。店内摆放着各式各样的鲜花，包括玫瑰、百合和向日葵，色彩鲜艳，香气扑鼻。背景是温馨的室内场景，光线柔和，透过窗户洒在花朵上。高清写实摄影，中景构图。",
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png"
}],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"image_count": 1
}
}使用限制
数据时效：任务task_id和 图像url均只保留 24 小时，过期后将无法查询或下载。
内容审核：输入的 prompt 和输出的图像均会经过内容安全审核，包含违规内容的请求将报错“IPInfringementSuspect”或“DataInspectionFailed”，具体参见错误信息。
网络访问配置：图像链接存储于阿里云 OSS，如果业务系统因安全策略无法访问外部OSS链接，请将以下 OSS 域名加入网络访问白名单。
# OSS域名列表 dashscope-result-bj.oss-cn-beijing.aliyuncs.com dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com dashscope-result-sh.oss-cn-shanghai.aliyuncs.com dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com dashscope-result-hy.oss-cn-heyuan.aliyuncs.com dashscope-result-cd.oss-cn-chengdu.aliyuncs.com dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com
计费与限流
错误码
如果模型调用失败并返回报错信息，请参见错误信息进行解决。
常见问题
Q: 如何查看模型调用量？
A: 模型调用完一小时后，请在模型观测页面，查看模型的调用次数、成功率等指标。如何查看模型调用记录？
该文章对您有帮助吗？