Qwen-Image-2.1 免费 API：魔搭接入步骤与当前额度规则

Qwen-Image-2.1 有公开的免费 API 入口：魔搭 ModelScope 的 API-Inference。 截至 2026 年 9 月 23 日，精确的 2.1 模型页已提供 Qwen/Qwen-Image-2.1 的异步调用示例。先完成魔搭账号与已实名认证阿里云账号的绑定，再取得 Access Token；免费调用受魔粒余额、动态并发限制和服务状态约束。

如果只是想用脚本试一下，按下面的魔搭流程接入即可。官方 Hugging Face Space 也公开了 Gradio 演示接口，可作为另一条体验路径，但它和正式的阿里云百炼 API 是不同服务。本文依据公开文档整理代码，未执行真实生图请求，不将文档可用等同于已验证生成成功。

先准备魔搭账号、实名信息和 Token

完成这三步，再运行代码，能避免把账号条件误当成程序错误。

1. 登录或注册 ModelScope，完善个人信息并验证邮箱。魔粒使用需要满足这些资料条件。
2. 绑定阿里云账号，并确保该阿里云账号已经完成实名认证。这是 API-Inference 接入说明列明的使用前提。
3. 按 Access Token 文档，在个人访问令牌页面取得自己的 Token。把它作为程序的 Bearer 凭据使用，不要写进公开仓库。

接着打开 Qwen-Image-2.1 模型页，查看“推理 API-Inference”，确认供应方为“魔搭社区”，代码中的型号为 Qwen/Qwen-Image-2.1。同时查看账号余额与页面展示的“预计魔粒扣减”。泛用接入文档中的旧 Qwen/Qwen-Image 示例不能代替这个精确型号。

免费额度怎么算：看魔粒，不能直接看“每天几张”

魔搭目前采用魔粒余额制。当前 API-Inference 限制说明按轻量、主流、旗舰模型列出每次 0.5、1、2 魔粒的档位，并要求以模型页面的预计扣减为准。本次在未登录的 Qwen-Image-2.1 页面上没有看到它的具体扣减数，因此不能据此承诺每天能生成多少张。

魔粒说明列出的日常获取规则如下，实际到账与到期时间请看自己的账户记录：

因此，即使满足条件获得了两项登录奖励，也不能直接说“每天免费 250 张”。需要先知道 2.1 当前扣减，再考虑其他功能的消耗和额度到期。旧教程中的固定每日调用次数，不应继续当作现行规则使用。

免费服务的用途同样明确：魔搭将它定位为非商业化、非盈利的体验产品，并发会随平台压力动态调整，目标是保障开发者单并发正常使用。适合先验证自己的生图流程；需要高并发或 SLA 的线上业务，应另外核对商业服务的型号、条款与费用。

Python 完整流程：提交任务、查询状态、保存图片

魔搭的示例是异步请求。POST 返回 task_id 只说明任务已经创建；只有查询到 task_status 为 SUCCEED，并取得 output_images，才进入下载步骤。以下代码依据模型页示例整理，另外加入环境变量、HTTP 超时和轮询截止时间，并保存为 PNG 以保留可能存在的透明通道。

先安装依赖，并在当前终端设置 Token：

bash
python -m pip install requests pillow
export MODELSCOPE_TOKEN='替换为你自己的魔搭访问令牌'

把下面代码保存为 generate_image.py，再运行 python generate_image.py。提示词可以直接改为中文。

python
import os
import time
from io import BytesIO
from pathlib import Path

import requests
from PIL import Image

BASE_URL = "https://api-inference.modelscope.cn"
TOKEN = os.environ["MODELSCOPE_TOKEN"]
HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

# 提交一次任务；记录 ID 后，后续只查询同一个任务。
response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={**HEADERS, "X-ModelScope-Async-Mode": "true"},
    json={
        "model": "Qwen/Qwen-Image-2.1",
        "prompt": "一只金色的小猫坐在窗边，柔和的晨光，水彩插画",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["task_id"]
Path("modelscope-task-id.txt").write_text(task_id, encoding="utf-8")
print("任务 ID：", task_id)

# 最多等待 10 分钟；这是本示例的等待上限，不是服务耗时承诺。
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(
        f"{BASE_URL}/v1/tasks/{task_id}",
        headers={**HEADERS, "X-ModelScope-Task-Type": "image_generation"},
        timeout=60,
    )
    response.raise_for_status()
    task = response.json()
    status = task["task_status"]

    if status == "SUCCEED":
        image_urls = task.get("output_images", [])
        if not image_urls:
            raise RuntimeError(f"任务成功但没有图片地址：{task_id}")
        # 图片地址使用独立请求，不向下载域名转发 API Token。
        image_response = requests.get(image_urls[0], timeout=120)
        image_response.raise_for_status()
        with Image.open(BytesIO(image_response.content)) as image:
            image.save("result.png", format="PNG")
        print("已保存 result.png")
        break

    if status == "FAILED":
        raise RuntimeError(f"生成任务失败，请保留任务 ID 排查：{task_id}")

    time.sleep(5)
else:
    raise TimeoutError(
        f"已停止等待，任务可能仍在运行。请查询原任务，不要重复提交：{task_id}"
    )

这段流程的成功判断是终端出现“已保存 result.png”，并且能打开保存的图片。它保存返回列表里的第一张图，不会自动批量提交请求。

如果脚本在轮询阶段超时或网络中断，先保留 modelscope-task-id.txt 中的 ID。重跑整个脚本会创建新任务；若只想查原任务，可以把下面的 TASK_ID 替换成已保存的 ID，在同一个已设置 Token 的终端执行：

bash
curl --fail-with-body \
  "https://api-inference.modelscope.cn/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer $MODELSCOPE_TOKEN" \
  -H "X-ModelScope-Task-Type: image_generation"

这个命令只返回任务状态，不会下载图片。确认 SUCCEED 后，从 output_images 取得地址再下载；不要因为第一次查询尚未完成就不断重发生成请求。如果连提交响应都没有收到，则尚不能确认任务是否创建，应先排查连接或服务状态。

请求没有出图，按失败位置排查

先分清是没有创建任务、任务生成失败，还是图片下载失败。这三种情况的下一步不同。

程序只能把错误暴露出来，不能绕过实名认证、额度或平台限流。发现模型页的接口示例发生变化时，优先采用当时该型号页面提供的代码。

备选入口：官方 Hugging Face Space 的演示 API

Qwen 官方 Space公开提供“通过 API 使用”入口，当前可用 Gradio 客户端调用 /generate_with_enhance。想从脚本连接公开演示，可以从该 Space 的 API 页面复制最新代码。

以下为基于当前公开接口说明的最小示例，未执行真实生成；其他参数使用当前接口默认值：

bash
python -m pip install gradio_client

python
from gradio_client import Client

client = Client("Qwen/Qwen-Image-2.1")
result = client.predict(
    input_images=[],
    original_prompt="一只金色的小猫坐在窗边，水彩插画",
    api_name="/generate_with_enhance",
)
print(result)

当前返回内容包括图片文件信息、seed 和改写后的提示词。演示服务可能排队、暂停或调整接口；公开客户端文档不代表固定免费额度或生产 SLA。如果连不上，先看 Space 是否运行以及最新 API 页面，不要照搬网上出现的内部后端地址。

这里有两个容易混淆的地方：

• Hugging Face 模型页显示尚无 Inference Provider 部署，指的是模型页的托管供应商通道；它不否定另一个 Space 已公开演示接口。
• 截至本文核验日，阿里云 Model Studio 正式 Qwen-Image API 型号表未列 2.1。不要把其他代际的模型 ID、价格或试用额度直接套给 2.1，也不要把 Space 接口当作普通 DashScope Key 的正式接入方式。

免费调用能否直接用于商业项目？

不能仅凭“免费”判断商用资格。魔搭免费 API-Inference 的服务限制已经说明它是非商业化体验产品。对模型本身，Qwen-Image-2.1 使用的是 Qwen Research License：其中模型材料的非商业使用范围为研究与评估，商业使用需要另外申请许可。

这不等同于对所有生成图片的权利作一概判断；如果要接入真实业务，需要分别确认托管服务条款、模型材料的适用授权，以及具体输出的使用条件。第三方页面出现“支持 API”或“免费测试积分”，也不能单独证明这些权限已经满足。

如果你的目标是自己掌控运行环境，可以继续看Qwen-Image-2.1 本地部署指南。下载权重和免费托管调用是两回事，本地运行仍需要计算资源。对于当前这条免费 API 路径，最实用的起点仍是：完成魔搭账号条件，查看 2.1 的预计扣减，再用一个异步任务验证自己的完整程序流程。