guide
Qwen Image 3.0 API 使用指南：通过 EvoLink 完成首次调用
EvoLink Team
Product Team
2026年7月22日
更新于 2026年8月5日
12 分钟阅读
这篇指南帮助 EvoLink 用户从 API Key 开始，完成第一个 Qwen Image 3.0 图像任务。最短链路是：调用
POST /v1/images/generations，模型填写 qwen-image-3.0-pro；保存返回的 id；再轮询 GET /v1/tasks/{task_id}，直到任务完成。截至 2026 年 8 月 5 日，Qwen Image 3.0 路由已在 EvoLink 上线，上游访问仍处于限量预览。开始关键生产流量前，应按本文配置超时、重试、结果存储和回退路由。
打开 Qwen Image 3.0 产品页
接入前准备
你需要：
- EvoLink 账户和 API Key；
- 足够完成测试的账户余额；
- 文生图提示词，或用于参考图编辑的 1-3 个公开图片 URL；
- 保存
task_id、任务状态和最终图片地址的数据表或任务系统。
| 项目 | 当前 EvoLink 契约 |
|---|---|
| Base URL | https://api.evolink.ai |
| 创建任务 | POST /v1/images/generations |
| 查询任务 | GET /v1/tasks/{task_id} |
| 模型 ID | qwen-image-3.0-pro |
| 模式 | 文生图；使用 1-3 张参考图的图生图/编辑 |
| 输出数量 | n: 1-6 |
| 尺寸 | auto 或支持的 WIDTHxHEIGHT |
| 鉴权 | Bearer API Key |
| 处理方式 | 异步任务 |
参数和端点的最终依据仍是 Qwen Image 3.0 产品页的 API 标签。本文重点是接入路径和生产决策，不替代实时 API Reference。
第一步：创建文生图任务
先把 API Key 放进环境变量。不要把密钥写进浏览器代码，也不要提交到 Git。
export EVOLINK_API_KEY="your_api_key"创建任务：
curl --request POST "https://api.evolink.ai/v1/images/generations" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"model": "qwen-image-3.0-pro",
"prompt": "一张结构化年度报告封面，清晰网格，深蓝与白色配色，精准小字，中间是一件写实玻璃产品",
"n": 1,
"size": "1024x1024",
"prompt_extend": false,
"watermark": false
}'初始响应会返回任务 ID 和处理状态：
{
"id": "task-unified-1772000000-a1b2c3d4",
"status": "processing"
}收到响应后立即保存返回的
id（轮询时作为 {task_id} 路径值），不要让创建任务的 HTTP 请求一直等待生成结束。第二步：轮询异步任务
查询任务，直到进入终态：
curl --request GET \
"https://api.evolink.ai/v1/tasks/task-unified-1772000000-a1b2c3d4" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}"完成后的任务会包含结果 URL 和用量信息：
{
"id": "task-unified-1772000000-a1b2c3d4",
"status": "completed",
"progress": 100,
"results": ["https://example-result-host/image_0.png"],
"usage": {
"credits_used": 5.5044,
"cost": { "credits": 5.5044, "usd": 0.0809, "cny": 0.5504 }
}
}把
completed、failed 和 cancelled 当作终态。轮询客户端可以从较短间隔开始，再逐步增加等待时间，并设置总超时。紧密循环不会加快生成，只会增加无效请求。
第三步：添加参考图进行编辑
图生图或参考图引导编辑需要传入
image_urls；纯文生图则应完全省略这个字段。curl --request POST "https://api.evolink.ai/v1/images/generations" \
--header "Authorization: Bearer ${EVOLINK_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"model": "qwen-image-3.0-pro",
"prompt": "保持产品主体一致，将场景重构为简洁的杂志广告，并加入精准的中英双语排版",
"image_urls": [
"https://your-cdn.example.com/product-reference.png"
],
"n": 2,
"prompt_extend": true
}'每次可使用 1-3 张参考图。提示词应明确每张图的职责：哪张控制主体、哪张控制风格、哪张控制构图。“把这些图合在一起”之类的模糊要求难以验收，也不利于复现。
会影响输出的核心参数
| 参数 | 作用 | 生产建议 |
|---|---|---|
prompt | 定义内容、版面、文字、风格和约束 | 复杂需求使用结构化分段，并单独审核必须出现的文字 |
image_urls | 参考图引导编辑 | 使用稳定的公网 HTTPS URL（不支持 base64 / Data URL），并遵守文件限制 |
n | 一次生成 1-6 个候选 | 只有多个候选能降低可用输出成本时才增加数量 |
size | 自动或指定输出尺寸 | 产品界面有固定比例时使用明确尺寸 |
prompt_extend | 自动丰富较短提示词 | 精确文字和版面必须保持不变时建议关闭 |
negative_prompt | 排除不希望出现的视觉特征 | 保持简短具体，不要重复正向提示词 |
seed | 提高测试的可复现程度 | 与提示词和模型 ID 一起保存，但不要假设绝对确定性 |
watermark | 控制是否添加模型水印 | 根据产品和合规需求选择 |
callback_url | 接收任务终态通知 | 仅用 HTTPS；处理器必须幂等并快速返回 |
当前 EvoLink API 文档是默认值和允许值的权威来源。预览期契约可能调整，不要把供应商直连 SDK 的字段直接复制到 EvoLink 请求中。
轮询和 Callback 应该怎么选
本地开发和低频工具优先使用轮询，调试简单，也不要求公网 Webhook。
需要在生成完成后自动唤醒 Worker 的应用，可以使用
callback_url。Callback 处理器应该：- 快速返回成功；
- 按自身安全策略验证请求；
- 使用
task_id作为幂等键； - 容忍重复投递；
- 必要时重新查询任务的当前状态；
- 把下载和存储工作放进队列，不在 Webhook 请求中执行重任务。
即使使用 Callback，也应保留定时对账任务，用来发现因为回调丢失或服务短暂不可用而长期停留在非终态的任务。
及时保存结果图片
当前文档说明生成结果链接是临时的。把通过验收的图片下载到自己的对象存储，不要把上游结果 URL 当作永久产品资产。
建议保存以下字段：
task_id
model_id
prompt_version
input_image_ids
request_parameters
submitted_at
completed_at
terminal_status
result_storage_urls
credits_used
review_status
fallback_task_id这些数据可以用于客服排查、成本分析、任务重放和模型迁移。
生产重试与回退策略
不要遇到失败就无条件重试，先区分失败类型。
| 失败类型 | 默认动作 | 原因 |
|---|---|---|
| 鉴权或余额错误 | 停止并告警 | 重试无法修复密钥或余额 |
| 参数或输入 URL 无效 | 修正请求，不自动重试 | 重复同一错误 Payload 没有意义 |
| 限流或暂时性上游错误 | 指数退避并加入随机抖动 | 状态可能自行恢复 |
| 任务超时但状态未知 | 先对账任务，再决定是否重建 | 避免重复生成和重复消费 |
| 生成成功但未通过 QA | 调整提示词或切换回退模型 | 这是质量问题，不是传输错误 |
上游访问和容量仍受限时，应在同一产品动作后保留另一个图像模型。回退时保留用户原始提示词和素材，只转换备选模型需要的参数。记录每次回退，避免无感切换污染评估数据。
第一个生产功能如何上线
不要一开始就做一个暴露所有参数的通用生成器。先选择一个边界清楚的任务，例如：
- 报告封面或信息图生成器；
- 多语言电商创意变体；
- 必须人工审核的教育图解草稿；
- 基于一张产品参考图的营销版面；
- 从结构化 Brief 生成故事板。
推荐上线顺序：
- 固定提示词模板，只开放少量必要参数。
- 用 20-50 组代表性输入做内部评估。
- 把结果保存到自有存储，并增加审核状态。
- 通过功能开关或小流量用户上线。
- 记录任务成功率、p50/p95 延迟、验收率、重试和每张可用图片成本。
- 在实测容量对自身流量稳定前保留回退。
如果你正在考虑迁移已有 Qwen 工作流，请先阅读 Qwen Image 3.0 vs 2.0 对比。
常见问题
EvoLink 使用的 Qwen Image 3.0 模型 ID 是什么？
使用
qwen-image-3.0-pro。哪个端点用于创建图像任务？
使用 Bearer API Key 和 JSON 请求体调用
POST https://api.evolink.ai/v1/images/generations。这是同步 API 吗？
不是。EvoLink 路由会返回
task_id，随后轮询 GET /v1/tasks/{task_id}，或提供支持的 HTTPS Callback URL。如何只使用文生图？
发送
prompt，并省略 image_urls。只有需要参考图引导编辑时才加入 1-3 个 image_urls。一次请求可以生成多少张图？
当前路由支持
n 为 1-6。增加数量前，应验证多个候选是否真的能降低每张可用图片成本。应该开启提示词扩展吗？
希望模型丰富短创意提示词时开启
prompt_extend；文字、标签和版面要求必须精确控制时关闭。生成图片应该如何保存？
把通过验收的结果下载到自己的对象存储，不要依赖临时结果链接作为永久资产。
Qwen Image 3.0 适合关键生产流量吗？
EvoLink 路由已上线，但上游访问仍受限，生产适用性取决于具体工作负载。先测量延迟、失败率、验收率和容量，并保留回退模型。
在哪里查看当前价格和参数？
访问 Qwen Image 3.0 产品页，其中包含实时价格模块、Playground 和 API 参考。
