Qwen Image 3.0 API 价格、接入与生产实践指南

Qwen Image 3.0 通过一套异步 API 同时支持文生图和参考图编辑。使用 APIMart 时，你需要先提交任务，再轮询任务状态，并在任务完成后取得一张或多张生成图片。

本文集中介绍接入前最重要的内容：Standard 与 Pro 的当前价格、身份验证、请求参数、响应解析、轮询、重试和输出存储。若想进一步了解模型能力与基准表现，可阅读 Qwen Image 3.0 发布指南。

Qwen Image 3.0 价格与访问

APIMart 提供两个 Qwen Image 3.0 模型 ID：

• qwen-image-3.0：Standard 标准版
• qwen-image-3.0-pro：Pro 专业版

该 API 按生成图片数量计费，而不是按输入 Token 计费。下表为 APIMart 价格页面在 2026 年 8 月 27 日列出的价格，后续可能调整。

Standard 与 Pro 价格对比

Standard 当前列出的 1K 与 2K 价格相同；Pro 的 2K 价格是 1K 的两倍。根据 Qwen Image 3.0 API 文档，生成失败会退还费用，参考图片本身不会产生额外生成费用。

估算实际工作负载

基础计算公式如下：

月度成本 = 成功生成的图片数 × 每张图片价格

n 控制一次请求返回的图片数量，因此设置 n: 4 的请求最多会按四张图片计费。预算时需要同时考虑提示词实验、多个变体和重新生成的图片。

大多数草稿和常规素材可以先使用 Standard。只有在文字渲染、构图或细节提升足以抵消额外成本时，再选择 Pro。使用 Pro 时，可在迭代阶段采用 1K，把 2K 留给已经确认的高分辨率成品。

获取访问权限与身份验证

首先注册 APIMart 账号、充值足够余额，并在控制台生成 API Key。API Key 必须保存在服务端 Secret 或环境变量中，绝不能暴露在浏览器代码或 NEXT_PUBLIC_* 变量里。

Base URL 与 Bearer Token

本文示例统一使用以下 Base URL：

https://api.apimart.ai/v1

通过 Bearer Token 发送 API Key：

Authorization: Bearer <your_api_key>
Content-Type: application/json

API Key 缺失或无效通常会返回 401，余额不足可能返回 402，触发限流则可能返回 429。服务端应记录响应正文和请求上下文，但写入日志前必须隐藏 API Key。

图像生成、编辑与异步工作流

生成和编辑都使用 POST /v1/images/generations。接口不会等待图片生成完毕，而是先返回一个任务 ID。

核心请求参数

使用自定义尺寸时，每条边应在 512～2,048 像素之间，宽高比应在 1:8～8:1 之间。参考图支持 JPEG、PNG、BMP、TIFF、WebP 和 GIF，文档规定每张不得超过 10 MB。参数限制可能调整，发布前应重新检查生成接口文档。

Qwen Image 3.0 官方公告称其原生支持 12 种语言的文字渲染。生成文字密集型图片时，应把要求完全一致的文案放在引号内，并在目标分辨率下验证拼写、字体风格和版式。

文生图请求示例

{
  "model": "qwen-image-3.0",
  "prompt": "简洁的商品横幅，必须准确显示文字‘夏日特惠’，粗体几何字体，暖橙色背景",
  "resolution": "1K",
  "size": "16:9",
  "n": 1,
  "prompt_extend": true
}

参考图编辑示例

需要变换或重新设计已有图片时，增加 image_urls：

{
  "model": "qwen-image-3.0-pro",
  "prompt": "保持商品形状完全不变，把背景替换为光线柔和的摄影棚场景",
  "image_urls": [
    "https://example.com/reference-product.png"
  ],
  "resolution": "2K",
  "n": 1
}

参考图片地址必须能够被 API 访问。对于私有文件，可以使用有效期足以覆盖提交和处理过程的签名 URL；适合时也可以使用受支持的 Data URL。

异步任务工作流

完整请求流程分为三步：

1. 通过 POST /v1/images/generations 提交生成任务。
2. 从响应中的 data[0].task_id 读取任务 ID。
3. 轮询 GET /v1/tasks/{task_id}，直到任务完成或失败。

提交响应

成功提交后的响应结构如下：

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example"
    }
  ]
}

不要从顶层对象读取 task_id，它位于 data 数组的第一个元素中。

轮询与完成结果

建议每 3～5 秒轮询一次，避免连续发送大量状态请求。任务完成后，生成文件位于 data.result.images：

{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": [
            "https://example-cdn.com/generated-image.png"
          ]
        }
      ]
    }
  }
}

APIMart 当前的生成接口文档说明，完成后的图片会被镜像到平台 CDN 并长期提供访问。即便如此，如果业务对保留期限、删除、访问策略或交付性能有明确要求，仍应把确认后的素材复制到自己控制的存储中。

代码集成示例

Python 集成

下面的服务端示例会提交一个任务，每三秒轮询一次，并在三分钟后停止等待：

import os
import time
import requests

API_KEY = os.environ["QWEN_API_KEY"]
BASE_URL = "https://api.apimart.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def generate_image(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=HEADERS,
        json={"model": "qwen-image-3.0", "prompt": prompt, "resolution": "1K", "n": 1, "prompt_extend": True},
        timeout=30,
    )
    response.raise_for_status()
    task_id = response.json()["data"][0]["task_id"]
    deadline = time.monotonic() + 180

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        task = poll.json()["data"]
        if task["status"] == "completed":
            return task["result"]["images"][0]["url"][0]
        if task["status"] == "failed":
            raise RuntimeError(task.get("fail_reason", "Generation failed"))
        time.sleep(3)

    raise TimeoutError(f"Task {task_id} did not finish within 180 seconds")

实际应用中，应在开始轮询前持久化任务 ID。即使 Worker 重启，其他 Worker 也能从保存的任务继续处理，而不必重新提交并为重复生成付费。

JavaScript 集成

以下代码只能运行在可信的服务端环境中：

const apiKey = process.env.QWEN_API_KEY;
const baseUrl = "https://api.apimart.ai/v1";
const headers = { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" };

async function requestJson(url, options = {}) {
  const response = await fetch(url, { ...options, headers });
  const payload = await response.json();
  if (!response.ok) throw new Error(`APIMart ${response.status}: ${JSON.stringify(payload)}`);
  return payload;
}

async function generateImage(prompt) {
  const submission = await requestJson(`${baseUrl}/images/generations`, {
    method: "POST",
    body: JSON.stringify({
      model: "qwen-image-3.0", prompt, resolution: "1K", n: 1, prompt_extend: true,
    }),
  });
  const taskId = submission.data[0].task_id;
  const deadline = Date.now() + 180_000;

  while (Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    const { data: task } = await requestJson(`${baseUrl}/tasks/${taskId}`);
    if (task.status === "completed") return task.result.images[0].url[0];
    if (task.status === "failed") throw new Error(task.fail_reason ?? "Generation failed");
  }
  throw new Error(`Task ${taskId} did not finish within 180 seconds`);
}

如需快速手动测试，可使用相同的提交与轮询流程：

curl -X POST https://api.apimart.ai/v1/images/generations \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0","prompt":"极简风格的商品摄影","resolution":"1K","n":1}'

curl https://api.apimart.ai/v1/tasks/<task_id> \
  -H "Authorization: Bearer <your_api_key>"

生产集成检查清单

一次 API 调用成功只是开始。可靠的图片生成管线还需要受限重试、持久化任务状态、可观测性和可控存储。

错误与重试策略

遇到含义不明确的网络超时时，不要直接重新提交生成请求。如果服务端已经接收原请求，第二次提交会产生重复任务和额外费用。应持久化每个已返回的任务 ID，并分别处理“提交重试”和“轮询重试”。

上线前检查

• API Key 只保存在服务端 Secret 中。
• 提交前校验 prompt、resolution、size、n 和参考图。
• 持久化任务 ID 与当前状态。
• 每 3～5 秒轮询一次，并设置应用层超时。
• 对 429 和可重试的 5xx 使用带随机抖动的指数退避。
• 根据实际速率限制和延迟控制并发。
• 分别统计完成、失败、超时和重复任务。
• 需要明确控制保留期限时，把确认后的输出复制到自己的存储。
• 生产发布前重新检查 Qwen Image 3.0 模型页、价格页和 API 文档。

使用 Qwen Image 3.0 生成图像

通过 APIMart 统一 API 测试 Standard 与 Pro，对比 1K 和 2K 输出，并将图像工作流从原型验证平稳推进到生产环境。

体验 Qwen Image 3.0

常见问题

轮询多久后应该超时？

APIMart 建议每 3～5 秒轮询一次，并将客户端超时设置在三分钟左右。可以把它作为起点：根据真实延迟调整产品超时，同时保留任务 ID，便于后续核对已经超时的任务。

Qwen Image 3.0 结果链接会在 24 小时后过期吗？

当前 APIMart 生成接口文档说明，输出会被镜像到平台 CDN 并长期可用，因此早先的“24 小时过期”说法不适用于此接入。对于业务关键素材，仍应存入自己控制的基础设施，而不是依赖没有明确期限承诺的外部存储。

可以发送 Base64 参考图吗？

可以。当前 API 文档允许在 image_urls 中提供 1～3 个公开 HTTP/HTTPS 地址或受支持的 Base64 Data URL。每张参考图都必须符合文档规定的格式和 10 MB 限制。

应该选择 1K 还是 2K？

快速迭代以及不需要极致细节的素材可以使用 1K；包含大量文字、精细边缘或用于大尺寸展示的最终图片适合 2K。Standard 当前两个分辨率价格相同，而 Pro 2K 比 Pro 1K 更贵，因此需要综合比较延迟、画质和成本。