通过文生图API，您可以基于文本描述创造出全新的图像。阿里云百炼提供两大系列模型：
千问（Qwen-Image）: 擅长渲染复杂的中英文文本。
万相（Wan系列）: 用于生成写实图像和摄影级视觉效果。
模型效果
千问（Qwen-image）
复杂文字
| 超长段落
| 复杂布局
|
海报制作
| 插画设计
| 写实摄影
|
万相
人像写真
| 写实摄影
| 绘画流派
|
文字生成
| 海报设计
| 组图生成
|
支持的模型
模型选型
复杂文字渲染（如海报、对联）：首选
qwen-image-2.0-pro、wan2.6-t2i。写实场景和摄影风格（通用场景）：可选万相模型，如
wan2.6-t2i、wan2.5-t2i-preview。需要自定义输出图像分辨率：推荐
qwen-image-2.0系列或万相模型。qwen-image-2.0系列支持自由设置宽高，输出图像总像素在[512*512, 2048*2048]之间；万相模型如wan2.6-t2i，输出图像总像素在[1280*1280, 1440*1440]之间。qwen-image-max、qwen-image-plus系列模型仅支持5种固定尺寸：1664*928(16:9)、928*1664(9:16)、1328*1328(1:1)、1472*1104(4:3)、1104*1472(3:4)。
快速开始
前提条件
在调用前，请获取API Key，再配置API Key到环境变量。如果通过DashScope SDK进行调用，还需要安装SDK。
示例代码
调用方式说明：
千问文生图模型均支持同步调用，其中qwen-image-plus、qwen-image模型支持异步调用，详情请参见千问-文生图。
万相文生图模型均支持异步调用，其中wan2.6-t2i支持同步调用，详情请参见万相-文生图V2。
同步调用
Python
请求示例
import json
import os
import dashscope
from dashscope import MultiModalConversation
# 以下为新加坡地域url，若使用北京地域的模型，需将url替换为：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
messages = [
{
"role": "user",
"content": [
{"text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."}
]
}
]
# 新加坡和北京地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")
response = MultiModalConversation.call(
api_key=api_key,
model="qwen-image-2.0-pro",
messages=messages,
result_format='message',
stream=False,
watermark=False,
prompt_extend=True,
negative_prompt="低分辨率，低画质，肢体畸形，手指畸形，画面过饱和，蜡像感，人脸无细节，过度光滑，画面具有AI感。构图混乱。文字模糊，扭曲。",
size='2048*2048'
)
if response.status_code == 200:
print(json.dumps(response, ensure_ascii=False))
else:
print(f"HTTP返回码：{response.status_code}")
print(f"错误码：{response.code}")
print(f"错误信息：{response.message}")
print("请参考文档：https://www.alibabacloud.com/help/zh/model-studio/error-code")响应示例
图像链接的有效期为24小时，请及时下载图像。
{
"status_code": 200,
"request_id": "d2d1a8c0-325f-9b9d-8b90-xxxxxx",
"code": "",
"message": "",
"output": {
"text": null,
"finish_reason": null,
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
}
]
}
}
]
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"width": 2048,
"image_count": 1,
"height": 2048
}
}Java
请求示例
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
public class QwenImage {
static {
// 以下为新加坡地域base_url，若使用北京地域的模型，需将base_url替换为：https://dashscope.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// 新加坡和北京地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若没有配置环境变量，请用百炼API Key将下行替换为：static String apiKey="sk-xxx"
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void call() throws ApiException, NoApiKeyException, UploadFileException, IOException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("text", "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.")
)).build();
Map<String, Object> parameters = new HashMap<>();
parameters.put("watermark", false);
parameters.put("prompt_extend", true);
parameters.put("negative_prompt", "低分辨率，低画质，肢体畸形，手指畸形，画面过饱和，蜡像感，人脸无细节，过度光滑，画面具有AI感。构图混乱。文字模糊，扭曲。");
parameters.put("size", "2048*2048");
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(apiKey)
.model("qwen-image-2.0-pro")
.messages(Collections.singletonList(userMessage))
.parameters(parameters)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
call();
} catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
响应示例
图像链接的有效期为24小时，请及时下载图像。
{
"requestId": "5b6f2d04-b019-40db-a5cc-xxxxxx",
"usage": {
"image_count": 1,
"width": 2048,
"height": 2048
},
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
}
]
}
}
]
}
}curl
请求示例
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "qwen-image-2.0-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "冬日北京的都市街景，青灰瓦顶、朱红色外墙的两间相邻中式商铺比肩而立，檐下悬挂印有剪纸马的暖光灯笼，在阴天漫射光中投下柔和光晕，映照湿润鹅卵石路面泛起细腻反光。左侧为书法店：靛蓝色老旧的牌匾上以遒劲行书刻着“文字渲染”。店门口的玻璃上挂着一幅字，自上而下，用田英章硬笔写着“专业幻灯片 中英文海报 高级信息图”，落款印章为“1k token”朱砂印。店内的墙上，可以模糊的辨认有三幅竖排的书法作品，第一幅写着着“阿里巴巴”，第二幅写着“通义千问”，第三福写着“图像生成”。一位白发苍苍的老人背对着镜头观赏。右侧为花店，牌匾上以鲜花做成文字“真实质感”；店内多层花架陈列红玫瑰、粉洋牡丹和绿植，门上贴了一个圆形花边标识，标识上写着“2k resolution”，门口摆放了一个彩色霓虹灯，上面写着“细腻刻画 人物 自然 建筑”。两家店中间堆放了一个雪人，举了一老式小黑板，上面用粉笔字写着“Qwen-Image-2.0 正式发布”。街道左侧，年轻情侣依偎在一起，女孩是瘦脸，身穿米白色羊绒大衣，肉色光腿神器。女孩举着心形透明气球，气球印有白色的字：“生图编辑二合一”。里面有一个毛茸茸的卡皮巴拉玩偶。男孩身着剪裁合体的深灰色呢子外套，内搭浅色高领毛衣。街道右侧，一个后背上写着“更小模型，更快速度”的骑手疾驰而过。整条街光影交织、动静相宜。"
}
]
}
]
},
"parameters": {
"negative_prompt": "低分辨率，低画质，肢体畸形，手指畸形，画面过饱和，蜡像感，人脸无细节，过度光滑，画面具有AI感。构图混乱。文字模糊，扭曲。",
"prompt_extend": true,
"watermark": false,
"size": "2048*2048"
}
}'curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "qwen-image-2.0-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."
}
]
}
]
},
"parameters": {
"negative_prompt": "低分辨率，低画质，肢体畸形，手指畸形，画面过饱和，蜡像感，人脸无细节，过度光滑，画面具有AI感。构图混乱。文字模糊，扭曲。",
"prompt_extend": true,
"watermark": false,
"size": "2048*2048"
}
}'响应示例
{
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"content": [
{
"image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"
}
],
"role": "assistant"
}
}
]
},
"usage": {
"height": 2048,
"image_count": 1,
"width": 2048
},
"request_id": "d0250a3d-b07f-49e1-bdc8-6793f4929xxx"
}异步调用
SDK 在底层封装了异步处理逻辑，上层接口表现为同步调用（即单次请求并等待最终结果返回）；而 curl 示例则对应两个独立的异步 API 接口：一个用于提交任务，另一个用于查询结果。
Python
请求示例
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
# 以下为新加坡地域base_url，各地域的base_url不同
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
# 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
# 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
message = Message(
role="user",
content=[
{
'text': '一间有着精致窗户的花店，漂亮的木质门，摆放着花朵'
}
]
)
print("----sync call, please wait a moment----")
rsp = ImageGeneration.call(
model="wan2.6-t2i",
api_key=api_key,
messages=[message],
negative_prompt="",
prompt_extend=True,
watermark=False,
n=1,
size="1280*1280"
)
print(rsp)
响应示例
url 有效期24小时，请及时下载图像。
{
"status_code": 200,
"request_id": "820dd0db-eb42-4e05-8d6a-1ddb4axxxxxx",
"code": "",
"message": "",
"output": {
"text": null,
"finish_reason": null,
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
"type": "image"
}
]
}
}
],
"audio": null,
"finished": true
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"characters": 0,
"image_count": 1,
"size": "1280*1280",
"total_tokens": 0
}
}Java
请求示例
import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Collections;
public class Main {
static {
// 以下为新加坡地域url，各地域的base_url不同
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey="sk-xxx"
// 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-t2i")
.n(1)
.size("1280*1280")
.negativePrompt("")
.promptExtend(true)
.watermark(false)
.messages(Collections.singletonList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageGeneration.call(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
basicCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}响应示例
url 有效期24小时，请及时下载图像。
{
"status_code": 200,
"request_id": "50b57166-eaaa-4f17-b1e0-35a5ca88672c",
"code": "",
"message": "",
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
"type": "image"
}
]
}
}
],
"finished": true
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"image_count": 1,
"size": "1280*1280",
"total_tokens": 0
}
}curl
说明
异步调用必须设置 Header 参数
X-DashScope-Async为enable。异步任务的
task_id查询有效期为 24 小时，过期后任务状态将变为UNKNOWN。
步骤1：发起创建任务请求
该请求会返回一个任务ID（task_id）。
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
"model": "wan2.6-t2i",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"text": "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵"
}
]
}
]
},
"parameters": {
"prompt_extend": true,
"watermark": false,
"n": 1,
"negative_prompt": "",
"size": "1280*1280"
}
}'步骤2：根据任务ID查询结果
使用上一步获取的 task_id，通过接口轮询任务状态，直到 task_status 变为 SUCCEEDED 或 FAILED。
将{task_id}完整替换为上一步接口返回的task_id的值。task_id查询有效期为24小时。
curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--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-2.0 系列：支持自由设置宽高，输出图像总像素需在512*512至2048*2048之间。默认分辨率为2048*2048。推荐分辨率：
2688*1536：16:91536*2688：9:162048*2048（默认值）：1:12368*1728：4:31728*2368：3:4
qwen-image-max、qwen-image-plus 系列：仅支持以下 5 种固定的分辨率：
1664*928（默认值）：16:91472*1104：4:31328*1328：1:11104*1472：3:4928*1664：9:16
万相 V2 版模型 (2.0 及以上版本)：支持在 [512, 1440] 像素范围内任意组合宽高，总像素不超过 1440*1440。常用分辨率：
1024*1024（默认值）：1:11440*810: 16:9810*1440: 9:161440*1080: 4:31080*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-2.0-pro模型，它具备更专业的文字渲染能力。