Qwen Image 2512 API 快速开始指南：几分钟内生成图像 (2026)
你好，我是Dora。我曾经花很多时间为产品创建图像：寻找资源、调整大小、重命名文件、整理文件夹…… 每一步都无休止地重复。这没什么难的，但很繁琐。后来，我尝试了Qwen Image 2512 API，发现我可以用仅几行代码自动化所有这些。
这不是广告。我只是分享当我尝试它时实际发生的事情 — 什么顺利进行了，我在哪里遇到困难，以及我如何让它变得可靠且有用。
WaveSpeed 快捷方式（如果你只想要结果）
如果你只想快速生成图像，而不想自己处理所有细节：
- WaveSpeed 已经提供了现成的 Qwen Image 2512 REST API（没有冷启动）。
- 使用 WaveSpeed 端点 + API 密钥 → 完成。
- 如果你想了解官方 DashScope 流程（以及常见的陷阱），继续阅读。
这个 API 实际能做什么？
简单来说：你输入文本描述，它给你一个图像。
例如，如果你写：
“一个整洁的桌子，上面有一个笔记本和一株植物，柔和的光线照射”
几秒钟后，你得到一个与你的描述相匹配的图像 — 你可以自动将其保存到你的计算机。
它擅长的事情：
- 制作灵感板
- 快速生成缩略图
- 在文档中添加占位符图像
- 为产品创建原型视觉效果
我注意到的：
第一次使用时，它似乎并不比手动查找图像快多少。但运行两三次后，我意识到我不再需要为”这个大小应该是多少？“或”我应该如何命名这个文件？“而烦恼。它为我节省的不仅是时间，还有精力。
图像格式和存储
- 格式： PNG，默认自动生成
- 图像存储位置：
- API 返回一个指向图像的链接（URL）
- 该链接指向阿里云服务器
- 重要提示：链接仅在 24 小时内有效；之后，它将过期
- 所以你需要及时将其下载到你的计算机
注意： API 不直接给你图像文件。如果你想在本地保存它，你需要在代码中添加一个下载步骤（稍后解释）。
开始前：你需要什么
步骤 1：获取帐户和 API 密钥
- 注册阿里云账户
- 前往模型工作室控制台
- 生成 API 密钥（就像证明你身份的密钥）
- 将密钥保存为名为
DASHSCOPE_API_KEY的环境变量
环境变量：
把它想象成计算机上的一个特殊位置，你的密钥存放在那里，这样你的代码可以自动找到它，而无需每次都复制粘贴。
提示：
- 对于测试，你可以将其存储在
.env文件中 - 对于实际使用，使用安全的密钥管理工具更安全
- 北京和新加坡地区有不同的密钥 — 不要混淆它们
步骤 2：选择一个工具
有三种主要方式，从最简单到最复杂：
-
cURL（最简单）
- 适合快速测试 API 是否有效
- 不需要编程，只需粘贴命令
- 建议首次尝试
-
Python（最常见）
- 适合为重复使用构建小工具
- 我使用官方的 DashScope SDK 来自动处理许多细节
- 一些基本的 Python 知识会有帮助
-
Node.js（对前端开发者友好）
- 如果你是前端开发者，这也可以
- 原理相同，虽然我不会在这里涵盖
先尝试游乐场：
如果你只想快速测试结果，Wavespeed 游乐场让你在浏览器中生成图像。非常适合偶尔使用。对于批量生成或自动化，继续阅读以学习如何使用 API。
快速入门：使用 cURL 测试
打开你的终端（Mac）或命令提示符（Windows）并粘贴以下内容：
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-max",
"input": {
"messages": [
{
"role": "user",
"content": [
{"text": "一个整洁的桌子，上面有一个笔记本和一株植物，柔和的光线照射"}
]
}
]
},
"parameters": {
"size": "1024*1024"
}
}'按 Enter，等待几秒钟，你将看到一个 JSON 响应，其中包含一个指向你的图像的链接。
我遇到的陷阱
- 模型名称必须是
qwen-image-max，而不是qwen-image-2512或其他任何名称。 - 大小格式使用星号
1024*1024，而不是1024x1024。 - 对于新加坡地区，将 URL 更改为：
https://dashscope-intl.aliyuncs.com/api/v1/...
如果你正在构建类似生产的东西，官方 DashScope 流程完全可行 — 但它带有运营细节（地区、URL 生命周期、重试）。这正是我喜欢使用 WaveSpeed 进行日常工作的原因：它在现成的 REST API 后面给我 Qwen Image 2512，所以我可以专注于提示和输出管理，而不是管道工作。
参数说明
必需
-
model
"qwen-image-max"是 Qwen-Image-2512 的官方名称- 还有
"qwen-image-plus"，类似但更便宜
-
input.messages
- 一个包含一个元素的数组
text是你的描述- 最多 800 个字符（大约 400 个中文字符）
可选（如果省略则使用默认值）
-
parameters.size
1664*928（16:9 横向）1472*1104（4:3）1328*1328（1:1 正方形，默认值）1104*1472（3:4 纵向）928*1664（9:16 纵向）
-
parameters.negative_prompt
- 你不想要的东西：例如，
"低分辨率、模糊、扭曲、过度饱和" - 最多 500 个字符
- 你不想要的东西：例如，
-
parameters.prompt_extend
- 默认为
true - 自动丰富你的描述
- 如果你想严格控制，将其关闭
- 默认为
-
parameters.watermark
- 默认
false - 如果为
true，添加”Qwen-Image”水印
- 默认
-
parameters.seed
- 范围
0–2147483647 - 相同的种子 + 相同的描述 = 相同的图像
- 用于测试和比较结果
- 范围
API 响应示例
{
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxx"
}
]
}
}
]
},
"usage": {
"width": 1328,
"image_count": 1,
"height": 1328
},
"request_id": "xxx"
}关键要点
- 图像 URL：
output.choices[0].message.content[0].image - 检查
finish_reason是否为"stop"以确认成功 - 链接持续 24 小时 — 及时下载
使用 Python 自动化
如果你想进行批量生成或构建小工具：
import os
import time
import requests
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
API_KEY = os.getenv("DASHSCOPE_API_KEY")
ENDPOINT = "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"
HEADERS = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
def generate_image(prompt: str, size="1328*1328"):
payload = {
"model": "qwen-image-max",
"input": {
"messages": [{"role": "user", "content": [{"text": prompt}]}]
},
"parameters": {"size": size, "prompt_extend": True, "watermark": False}
}
r = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=120)
r.raise_for_status()
data = r.json()
choices = data.get("output", {}).get("choices", [])
if not choices:
raise ValueError(f"没有生成图像：\n{data}")
content = choices[0].get("message", {}).get("content", [])
if not content:
raise ValueError(f"内容为空：\n{data}")
image_url = content[0].get("image")
if not image_url:
raise ValueError(f"没有图像 URL：\n{data}")
img_response = requests.get(image_url)
img_response.raise_for_status()
file_name = PurePosixPath(unquote(urlparse(image_url).path)).parts[-1]
ts = int(time.time())
path = f"qwen_image_{ts}_{file_name}"
with open(path, "wb") as f:
f.write(img_response.content)
return path
if __name__ == "__main__":
output_path = generate_image("一个整洁的桌子，上面有一个笔记本和一株植物，柔和的光线照射")
print("图像保存在：", output_path)我在测试中学到的
- 错误的模型名称会导致失败（
qwen-image-plus→qwen-image-max） - 错误的大小格式（
1328x1328而不是1328*1328） - 响应结构与文档略有不同；检查图像 URL
- 忘记下载图像会导致链接在 24 小时后过期
使用官方 SDK
import os
import json
from dashscope import MultiModalConversation
api_key = os.getenv("DASHSCOPE_API_KEY")
messages = [{"role": "user", "content": [{"text": "一个整洁的桌子，上面有一个笔记本和一株植物，柔和的光线照射"}]}]
response = MultiModalConversation.call(
api_key=api_key,
model="qwen-image-max",
messages=messages,
result_format='message',
stream=False,
watermark=False,
prompt_extend=True,
size='1328*1328'
)
if response.status_code == 200:
print(json.dumps(response, ensure_ascii=False))
image_url = response.output.choices[0].message.content[0]['image']
print(f"图像 URL：{image_url}")
else:
print(f"错误：{response.code} - {response.message}")快速参数参考
| 参数 | 建议值 | 注释 |
|---|---|---|
| size | 1328*1328 | 正方形，速度和质量平衡 |
| prompt_extend | TRUE | 让 AI 丰富你的描述 |
| seed | 固定数字 | 用于测试以比较结果 |
| negative_prompt | 根据需要 | 例如，“模糊、低质量、扭曲” |
何时更改种子
- 固定种子 → 比较提示变化
- 不同的种子 → 生成多个不同的图像
常见错误和修复
401 未授权→ 错误的 API 密钥、错误的地区或缺少图像权限429 速率限制→ 请求过多；添加延迟或升级配额- 超时/网络问题 → 增加超时，立即下载
我添加的小改进
- 用于测试提示的固定种子 → 更容易比较结果
- 一致的文件命名：
{keyword}-{size}-{seed}.png - 配置文件管理：YAML 以避免硬编码参数
这适合谁
游乐场
- 偶尔生成图像
- 快速提示测试
- 不需要自动化
API
- 批量生成
- 工具或产品集成
- 计划或基于系统的使用
最终路径（选择适合你的）
路径 A — 快速和实用
- 对 Qwen Image 2512 使用 WaveSpeed 游乐场 API
- 最少设置，现成的 REST 端点
路径 B — 完全控制
- 如果你需要深度阿里云集成，直接使用 DashScope
我喜欢在后台悄悄工作的工具。为了学习和理解，官方流程很好。对于日常工作和更快地发货，WaveSpeed 为我节省了很多麻烦。
