通过文生图API,您可以基于文本描述创造出全新的原创图像。阿里云百炼提供两大系列模型:
通义千问(Qwen-Image): 擅长渲染复杂的中英文文本。
通义万相(Wan系列): 用于生成写实图像和摄影级视觉效果。
通义千问 Qwen-Image
复杂文字 | 超长段落 | 复杂布局 |
电商海报 | 插画设计 | 写实摄影 |
通义万相
场景一:文字生成与创意设计 prompt = "生成一张新年祝福贺卡,背景有白雪,放鞭炮的小孩,蛇形成文案2025,并写上HAPPY NEW YEAR。" 效果对比:2.2模型的文字生成能力更强,适合创意设计场景。 | ||
文生图2.2(wan2.2-t2i-plus) | 文生图2.1(wanx2.1-t2i-turbo) | 文生图2.0(wanx2.0-t2i-turbo) |
场景二:语义理解与细节表现 prompt = "一个用针毡制作的圣诞老人手持礼物,旁边站着一只白色的猫咪,背景中有许多五颜六色的礼物。整个场景应该是可爱、温暖和舒适的,并且背景中还有一些绿色植物。" 效果对比:2.2和2.1模型的语义理解更加准确(如手持礼物),2.2模型画面细节更丰富(如礼物纹理)。 | ||
文生图2.2(wan2.2-t2i-plus) | 文生图2.1(wanx2.1-t2i-turbo) | 文生图2.0(wanx2.0-t2i-turbo) |
场景三:人像创作 prompt = "中国女孩,圆脸,看着镜头,优雅的民族服装,商业摄影,室外,电影级光照,半身特写,精致的淡妆,锐利的边缘。 " 效果对比:2.2生图更稳定,2.0在质感人像上同样出色。 | ||
文生图2.2(wan2.2-t2i-plus) | 文生图2.1(wanx2.1-t2i-turbo) | 文生图2.0(wanx2.0-t2i-turbo) |
模型选型
复杂文字渲染(如海报、对联):首选
qwen-image-plus
。写实场景和摄影风格(通用场景):可选通义万相模型,推荐最新版本,如
wan2.2-t2i-plus
、wan2.2-t2i-flash
。plus 代表“专业版”,注重最高图像质量;flash 或 turbo 代表“极速版”,注重 API 响应速度。
需要自定义输出图像分辨率:推荐通义万相模型,如
wan2.2-t2i-flash
,支持 [512, 1440] 像素范围内的任意宽高组合。通义千问Qwen-Image仅支持5种固定尺寸:1664*928(16:9)、928*1664(9:16)、1328*1328(1:1)、1472*1140(4:3)、1140*1472(3:4)。
成本极度敏感,可接受基础质量:可选择
wanx2.0-t2i-turbo
,价格较低,请参见计费与限流。
快速开始
前提条件
在调用前,请获取API Key,再配置API Key到环境变量。如果通过DashScope SDK进行调用,还需要安装SDK。
示例代码
调用方式说明:通义千问Qwen-Image支持同步和异步调用,通义万相仅支持异步调用。
异步调用:两者API 兼容,只需更改
model
参数即可轻松切换。例如,使用通义万相模型时,将 model 设置为 "wan2.2-t2i-flash"。同步调用:仅通义千问Qwen-Image支持,调用请参见通义千问 Qwen-Image API参考。
下文示例均为异步调用方式。示例代码以 qwen-image-plus 为例,但同样适用于通义万相模型。
SDK 在底层封装了异步处理逻辑,上层接口表现为同步调用(即单次请求并等待最终结果返回);而 curl 示例则对应两个独立的异步 API 接口:一个用于提交任务,另一个用于查询结果。
Python
请求示例
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('----同步调用,请等待任务执行----')
rsp = ImageSynthesis.call(api_key=api_key,
model="qwen-image-plus",
prompt=prompt,
n=1,
size='1328*1328',
prompt_extend=True,
watermark=True)
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('同步调用失败, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
响应示例
url 有效期24小时,请及时下载图像。
{
"status_code": 200,
"request_id": "03b1ef03-480d-4ea5-ba52-xxxxxx",
"code": null,
"message": "",
"output": {
"task_id": "3cefd9bc-fcb2-4de9-a8bc-xxxxxx",
"task_status": "SUCCEEDED",
"results": [
{
"url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxxxx",
"orig_prompt": "一副典雅庄重的对联悬挂于厅堂之中,房间是个安静古典的中式布置,桌子上放着一些青花瓷,对联上左书“义本生知人机同道善思新”,右书“通云赋智乾坤启数高志远”, 横批“智启通义”,字体飘逸,中间挂在一着一副中国风的画作,内容是岳阳楼。",
"actual_prompt": "一副典雅庄重的对联悬挂于中式厅堂正中,整体空间为安静、古色古香的中国传统布置。厅堂内木质家具沉稳大气,墙面为淡色仿古纸张质感,地面铺设深色木质地板,营造出宁静而庄重的氛围。对联以飘逸的书法字体书写,左侧上联为“义本生知人机同道善思新”,右侧下联为“通云赋智乾坤启数高志远”,横批“智启通义”,文字排列对称,墨色深邃,书法流畅有力,体现出浓厚的文化气息与哲思内涵。\n\n对联中央悬挂一幅中国风画作,内容为岳阳楼,楼阁依水而建,背景为浩渺洞庭湖,远处山峦起伏,云雾缭绕,画面采用传统水墨技法绘制,笔触细腻,意境悠远。画作下方为一张中式红木长桌,桌上错落摆放着几件青花瓷器,包括花瓶与茶具,瓷器釉色清透,纹饰典雅,与整体环境风格和谐统一。整体画面风格为中国古典水墨风,空间布局层次分明,氛围宁静雅致,展现出浓厚的东方文化底蕴。"
}
],
"submit_time": "2025-09-09 13:41:54.041",
"scheduled_time": "2025-09-09 13:41:54.087",
"end_time": "2025-09-09 13:42:22.596"
},
"usage": {
"image_count": 1
}
}
Java
请求示例
// 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.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;
public class Text2Image {
static {
// 以下为北京地域url,若使用新加坡地域的模型,需将url替换为:https://dashscope-intl.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
}
// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey="sk-xxx"
// 新加坡和北京地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException {
String prompt = "一副典雅庄重的对联悬挂于厅堂之中,房间是个安静古典的中式布置,桌子上放着一些青花瓷,对联上左书“义本生知人机同道善思新”,右书“通云赋智乾坤启数高志远”, 横批“智启通义”,字体飘逸,中间挂在一着一副中国风的画作,内容是岳阳楼。";
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", true);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("qwen-image-plus")
.prompt(prompt)
.n(1)
.size("1328*1328")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---同步调用,请等待任务执行----");
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);
}
//根据taskId获取任务结果
public void fetchTask() throws ApiException, NoApiKeyException {
String taskId = "your task id";
ImageSynthesis is = new ImageSynthesis();
// 如果设置了 DASHSCOPE_API_KEY 环境变量,apiKey 可以为 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": "f2153409-3950-9b73-9980-xxxxxx",
"output": {
"task_id": "2fc2e1de-0245-442d-b664-xxxxxx",
"task_status": "SUCCEEDED",
"results": [
{
"orig_prompt": "一副典雅庄重的对联悬挂于厅堂之中,房间是个安静古典的中式布置,桌子上放着一些青花瓷,对联上左书“义本生知人机同道善思新”,右书“通云赋智乾坤启数高志远”, 横批“智启通义”,字体飘逸,中间挂在一着一副中国风的画作,内容是岳阳楼。",
"actual_prompt": "一副典雅庄重的对联悬挂于中式厅堂中央,对联左侧书写“义本生知人机同道善思新”,右侧书写“通云赋智乾坤启数高志远”,横批为“智启通义”,整体采用飘逸洒脱的书法字体,墨色浓淡相宜,展现出浓厚的传统韵味。对联中间悬挂一幅中国风画作,描绘的是著名的岳阳楼景观:楼阁飞檐翘角,依水而建,远处湖光潋滟,烟波浩渺,天空中有几缕轻云缭绕,营造出诗意盎然的意境。背景房间为安静古典的中式布置,木质家具线条流畅,桌上摆放着数件青花瓷器,纹饰精美,釉色莹润。整体空间光线柔和,营造出庄重、宁静的文化氛围。画面风格为传统中国水墨风,笔触细腻,层次分明,充满古典美感。",
"url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxx"
}
]
},
"usage": {
"image_count": 1
}
}
curl
异步调用必须设置 Header 参数
X-DashScope-Async
为enable
。异步任务的
task_id
查询有效期为 24 小时,过期后任务状态将变为UNKNOWN
。适用于所有模型,新手建议使用 Postman调用API。
步骤1:发起创建任务请求
该请求会返回一个任务ID(task_id
)。
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen-image-plus",
"input": {
"prompt": "一副典雅庄重的对联悬挂于厅堂之中,房间是个安静古典的中式布置,桌子上放着一些青花瓷,对联上左书“义本生知人机同道善思新”,右书“通云赋智乾坤启数高志远”, 横批“智启通义”,字体飘逸,中间挂在一着一副中国风的画作,内容是岳阳楼。"
},
"parameters": {
"size": "1328*1328",
"n": 1,
"prompt_extend": true,
"watermark": true
}
}'
步骤2:根据任务ID查询结果
使用上一步获取的 task_id
,通过接口轮询任务状态,直到 task_status
变为 SUCCEEDED 或 FAILED。
请将86ecf553-d340-4e21-xxxxxxxxx
替换为真实的task_id。
curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
关键能力
1. 指令遵循(提示词)
参数:input.prompt
(必选)、input.negative_prompt
(可选)。
prompt(正向提示词):描述希望在画面中看到的内容、主体、场景、风格、光照和构图。文生图的核心控制参数。
negative_prompt(反向提示词):描述不希望在画面中出现的内容,如“模糊”、“多余的手指”等。仅用于辅助优化生成质量。
撰写技巧:一个结构化的 Prompt 通常能带来更好的效果,撰写技巧请参见文生图Prompt指南。
2. 开启prompt智能改写
参数: parameters.prompt_extend
(bool, 默认为 true)。
此功能可自动扩展和优化较短的Prompt,提升出图效果。开启此功能额外耗时 3-5 秒。此耗时为使用大模型改写文本。
实践建议:
建议开启:当输入 Prompt 较简洁或宽泛时,此功能可显著提升图像效果。
建议关闭:若需控制画面细节、或已提供详细描述,或对响应延迟敏感。请将参数
prompt_extend
显式设为false
。
3. 设置输出图像分辨率
参数: parameters.size (string),格式为 "宽*高"
。
通义千问 Qwen-Image:仅支持以下 5 种固定的分辨率:
1328*1328(默认值):1:1。
1664*928: 16:9。
928*1664: 9:16。
1472*1140: 4:3。
1140*1472: 3:4。
通义万相 V2 版模型 (2.0 及以上版本):支持在 [512, 1440]
像素范围内任意组合宽高,总像素不超过 1440*1440。常用分辨率:
1024*1024(默认值):1:1。
1440*810: 16:9。
810*1440: 9:16。
1440*1080: 4:3。
1080*1440: 3:4。
应用于生产环境
容错策略
处理限流:当 API 返回
Throttling
错误码或 HTTP 429 状态码时,表明已触发限流,限流处理请参见限流。异步任务轮询:轮询查询异步任务结果时,建议采用合理的轮询策略(如前30秒每3秒一次,之后拉长间隔),避免因过于频繁的请求而触发限流。为任务设置一个最终超时时间(如 2 分钟),超时后标记为失败。
风险防范
结果持久化:API 返回的图片 URL 有 24 小时有效期。生产系统必须在获取 URL 后立即下载图片,并转存至您自己的持久化存储服务中(如阿里云对象存储 OSS)。
内容安全审核:所有
prompt
和negative_prompt
都会经过内容安全审核。若输入内容不合规,请求将被拦截并返回DataInspectionFailed
错误。生成内容的版权与合规风险:请确保您的提示词内容符合相关法律法规。生成包含品牌商标、名人肖像、受版权保护的 IP 形象等内容可能涉及侵权风险,请您自行评估并承担相应责任。
API文档
计费与限流
模型免费额度和计费单价请参见图像生成。
计费规则
计费项:按成功生成的 图像张数 计费,采用按量后付费模式。
计费公式:费用 = 计费单价 × 图像张数。
抵扣顺序:优先消耗免费额度。额度用尽后,默认转为按量付费。
您可开启“免费额度用完即停”功能,以避免免费额度耗尽后产生额外费用。详情请参见免费额度。
失败不计费:模型调用失败或处理错误不产生任何费用,也不消耗免费额度。
免费额度
关于免费额度的领取、查询、使用方法等详情,请参见免费额度。
调用量查询
模型调用完约一小时后,请在模型观测页面,查看调用量、调用次数、成功率等指标。
限流
模型限流规则及常见问题,请参见限流。
错误码
如果模型调用失败并返回报错信息,请参见错误信息进行解决。
常见问题
Q: 图片 URL 多久会失效?我应该如何永久保存图片?
A: 图片 URL 的有效期为 24 小时。您必须在获取到 URL 后,立即通过程序下载图片,并将其保存到您自己的持久化存储中,例如本地服务器或阿里云对象存储 OSS。
Q: 调用API返回DataInspectionFailed错误,如何处理?
A: 该错误表示输入文本触发了内容安全审核。请检查并修改prompt或negative_prompt中的文本,移除可能违规的内容后重试。
Q: prompt_extend参数应该开启还是关闭?
A: 当输入的prompt比较简洁或希望模型发挥更多创意时,建议保持开启(默认)。当prompt已经非常详细、专业,或对API响应延迟有严格要求时,建议显式设置为false。
Q: 如何提升图像中文字的生成效果?
A: 如果业务强依赖于在图像中生成清晰、准确的文字,请使用qwen-image-plus模型,它是为此类场景专门训练的。