Draft

Call Qwen Image 3.0 for One Product Shot and One Edit on the 10-Image Free Quota

  • Not yet verified
  • Versions not pinned
  • 12 min read

Task

What you will complete

On Alibaba Model Studio's China site in Beijing, turn on 免费额度用完即停 / Free Quota Only for qwen-image-3.0, then run one product-style text-to-image call and one edit on that model's 10-image free grant, saving both PNGs before the documented result URLs expire.

Success criteria

  • product_shot.py completes one text-to-image call for the planned 1024×1024 mug shot and writes examples/out/mug-t2i.png.
  • A second call edits that result (glaze to matte sage green) through the same /images/generations path, not /images/edits, and writes examples/out/mug-edit.png.
  • Both result URLs are downloaded before the documented 24-hour expiry, and the two-call job stays inside the 10-image grant with the stop switch on.

What this is not

Not a prompt-fishing session, not an OpenAI /images/edits multipart guide, and not a walkthrough of qwen-image-3.0-pro, Wan 2.7, or the Singapore grant. The free allowance is too small for a dozen variations, and this page stays on two calls against the standard 3.0 grant.

Prerequisites

  • A China-site (aliyun.com) Beijing Model Studio account, with a remaining 10-image grant for qwen-image-3.0 still visible in the console.
  • 免费额度用完即停 (Free Quota Only) turned on for qwen-image-3.0 before either call.
  • Your workspace ID, used to build the Beijing compatible-mode/v1 base URL unless DASHSCOPE_BASE_URL is set.
  • Python and the official openai package.

Environment

DASHSCOPE_API_KEY
Beijing Model Studio API key
DASHSCOPE_WORKSPACE_ID
Workspace ID from the console, used when DASHSCOPE_BASE_URL is not set
DASHSCOPE_BASE_URL
Optional override, e.g. https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

Ten free images sounds like room to tinker. On Alibaba Cloud Model Studio’s China site in Beijing, it is not. Official pricing for qwen-image-3.0 gives a new-user grant of 10 images that input and output share, valid for 90 days. An edit spends the reference picture as well as the new one. This walkthrough budgets three of those ten on purpose: one product-style text-to-image call, then one color-change edit of the same mug.

Planned call What the grant is documented to spend
Text-to-image, n=1 0 input + 1 successful output = 1
Edit that result, one reference, n=1 1 input + 1 successful output = 2
Both calls 3 of 10

Sign up and verify on the Alibaba Cloud China site, aliyun.com. Complete 实名认证, then issue an ordinary Model Studio API key in 华北2 / China (Beijing). That combination does not require an overseas company. Open the Beijing console’s 免费额度 page and enable 免费额度用完即停 for qwen-image-3.0 (the English label is Free Quota Only) before you send either request. Official docs describe the control as off unless you turn it on. Skip that step, and a grant that runs out continues as pay-as-you-go at the Beijing list prices of CNY 0.18 per successful output image and CNY 0.02 per input image. With the switch on, the documented result past the grant is a refusal, not a paid image.

The prices, the 10-image rule, the request parameters, and the example JSON are taken from official Model Studio pages opened on 2026-11-17 (Asia/Shanghai), not from a run on this site. This draft includes no API transcript, no generated mug, and no measured latency. Every command below is planned. Not yet verified.

How many of the ten images does a generate-then-edit job use?

Three, if you keep both calls to one output and send a single reference into the edit. That is the reading of the China-site price table, which lists the Beijing grant for qwen-image-3.0 as 输入输出共 10张 — input and output images together, not ten generations.

The billing formula on the same pricing page is:

cost = input unit price × input images + output unit price × successfully generated images

Failed requests are documented as incurring no charge and not consuming the new-user grant. A request that asks for several outputs, and only gets some of them back, is billed for the successful ones in the official example. Each model’s grant is separate. Using up qwen-image-3.0 does not touch qwen-image-3.0-pro, and the platform will not switch models for you.

That is why a casual loop — four variants, then an edit of each favorite — can finish the grant in one sitting. The two calls above stay inside a third of it and still let you check both API modes.

Does the 10-image grant still appear on your Beijing account?

Look at the console first. The new-user quota rules start the 90-day clock at the later of Model Studio activation, the model’s release, or application approval. The model listing page records qwen-image-3.0-pro on 2026-07-20 and qwen-image-3.0 on 2026-08-04. Ninety days after 4 August 2026 is 2 November 2026. If your account was already open on the listing date, the expiry in the console may already have passed as of 17 November 2026.

A first-time activation on the China site can still receive the grant, because the Beijing price table still lists it and the quota article still says the platform issues new-user allowances on first activation. Confirm the remainder and the expiry on the 免费额度 page or the model’s page in the Beijing console before you send traffic. Use the date printed there; do not add ninety days to today and assume that is the deadline.

Turn the stop-when-exhausted switch on for qwen-image-3.0 on that same 免费额度 page, or on the model page, before the first request. Official docs say the control is off by default, that models without a grant cannot enable it, and that the mobile console cannot toggle it. After you flip it, wait a short time before calling; docs also warn that a change can take a while to apply. When it is on and the grant is gone, the documented result is HTTP 403 with AllocationQuota.FreeTierOnly. That refusal is the outcome you want. It is not a prompt to disable the switch and keep going.

A few site and key details matter as much as the switch:

  • On the China site, official pricing says image models receive a free grant only in 华北2 (Beijing). Other regions on that site show list prices and no grant. The international English price page inverts this: it lists a 10-image grant in Singapore and shows Beijing only as a paid USD rate card, with no grant column. If you registered on aliyun.com in mainland China, stay on that Beijing reading. The Singapore column belongs to a different site and account path, and a key issued in Beijing is not documented as carrying that Singapore grant.
  • Use a regular Model Studio API key, stored in DASHSCOPE_API_KEY. Dedicated Token Plan or Coding Plan keys are documented as bypassing the new-user grant, and the quota article warns that sending image models through a Token Plan text base URL can return HTTP 400.
  • Spend this walkthrough on qwen-image-3.0, not qwen-image-3.0-pro. Each ID has its own 10-image Beijing grant. The standard ID is enough for a mug shot, and its Beijing list price is CNY 0.18 at both 1K and 2K if a later call ever slipped past the grant. Pro is CNY 0.25 at 1K and CNY 0.50 at 2K, and is the better later choice for dense typography, not for these two calls.
  • qwen-image-2.1-pro and qwen-image-2.1-turbo also show a Beijing grant of 10 images on the China price page. Their tables list an output price only, and the image billing preamble says models with no input price are not charged for input. This page stays on 3.0, where input is priced and counted.

Why does the edit go to /images/generations, not /images/edits?

Because Model Studio put both modes on one OpenAI-compatible endpoint. The Qwen Image Generation and Editing API reference is explicit: omit image for text-to-image, send image for an edit. The image field is a platform extension on POST /compatible-mode/v1/images/generations. The official OpenAI /images/edits path, multipart upload, and mask are documented as unsupported. response_format=b64_json is also documented as ignored; the body still returns a URL.

The sample code in the Chinese reference is written for Beijing. The English version of the same page says its samples apply to Singapore. Use the Beijing host with a Beijing key:

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

{WorkspaceId} comes from the workspace details page in the Model Studio console. The same Chinese reference still treats the older host https://dashscope.aliyuncs.com as usable, and recommends moving to the workspace domain. The key, the host, and the model have to be in one region; a Beijing key pointed at a Singapore URL is a documented 401 mismatch.

Two request details are easy to copy wrong. OpenAI-compatible size uses an x (1024x1024). DashScope HTTP uses an asterisk (1024*1024). n must be an integer; a string "1" is documented to return 400. image, seed, negative_prompt, prompt_extend, prompt_extend_mode, enable_thinking, and watermark are not standard OpenAI Images fields. When you use the official Python OpenAI SDK, those fields belong in extra_body. A raw HTTP request can place them at the top level of the JSON body.

DashScope synchronous HTTP is the method the docs mark as recommended (POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation). This walkthrough uses the OpenAI-compatible path instead, because the SDK change is small and the /images/edits mismatch is the trap worth showing. Capabilities are documented as the same. Set the client timeout high; official examples use 600 seconds, because a short client timeout can look like a failure while the server still finishes — and a retry could spend another image.

What does a two-call product-shot script actually send?

A companion script lives in examples/product_shot.py. It passed python -m py_compile. It has not been executed against Model Studio, and this page does not attach a generated mug.

The planned request is narrow on purpose. One 1024×1024 PNG of a white ceramic mug with a plain OAK 12 oz wordmark, then one edit that changes only the glaze to matte sage green. n stays at 1. seed is 42, which official docs describe as making results relatively stable, not identical. Prompt rewriting stays at the documented default (prompt_extend true) so this page does not spend a third and fourth image comparing settings.

pip install -U openai
export DASHSCOPE_API_KEY='your-beijing-key'
export DASHSCOPE_WORKSPACE_ID='your-workspace-id'
# Optional override: export DASHSCOPE_BASE_URL='https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1'
python examples/product_shot.py

The first call is text-to-image:

response = client.images.generate(
    model="qwen-image-3.0",
    prompt=(
        "A studio product photograph of a plain white ceramic 12 oz coffee mug "
        "on a light oak table, soft even lighting, no people. The mug has a "
        "simple navy sans-serif wordmark that reads OAK 12 oz. Clean background, "
        "sharp focus, photorealistic, square crop."
    ),
    size="1024x1024",
    n=1,
    extra_body={"seed": 42, "watermark": False},
)

The second call uses the same method and the same size, and puts the first result URL in extra_body["image"]. Official docs accept a public HTTP or HTTPS URL, or a data:{MIME_type};base64,{base64_data} string. Reusing the first URL is the planned path; it has not been checked on a live key. If that URL were rejected, the script comments say to send the downloaded PNG as a data URI instead. That fallback has not been tested either. For qwen-image-3.0, you may send one to three reference images. This job sends one.

Download each PNG as soon as the URL comes back. Official docs say result links last 24 hours and are then cleared. The script writes them to examples/out/mug-t2i.png and examples/out/mug-edit.png.

What should you keep from the documented response?

Treat the following as the shape in the official reference, not as output this site has seen.

A successful OpenAI-compatible body is documented like this:

{
  "created": 1788339600,
  "data": [
    {
      "url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
    }
  ],
  "usage": {
    "output_height": 1024,
    "output_width": 1024,
    "input_image_count": 0,
    "input_image_type": "qima_input_1k",
    "output_image_count": 1,
    "output_image_type": "qima_output_1k"
  }
}

usage is image metering, not token counts. After an edit, input_image_count should be 1. The 1K / 2K type is documented as a pixel-area split: area ≤ 2,250,000 is qima_output_1k (or qima_input_1k); above that is 2K. A 1024×1024 frame is 1,048,576 pixels, so it should land in 1K. For qwen-image-3.0, 1K and 2K share the same Beijing list price anyway; they still each count as one image against the grant.

The OpenAI-compatible body does not include request_id. Official docs say it arrives in the x-request-id response header, as response._request_id on a successful Python SDK response, and as APIStatusError.request_id on a failure. Keep that ID if you have to ask about a call whose result you never saw.

Which settings spend the grant faster than they look?

n can be 1 through 6, and every successful image counts. Raising it to compare compositions is the fastest way to turn a two-call job into a six- or twelve-image job.

Extra reference images count too. qwen-image-3.0 accepts up to three. Each one is an input image on a billed call.

Retry habits matter more than the parameter list. Official docs say a failed request does not consume the grant. A client timeout, a dropped connection, or a process you killed is not the same thing as a documented failure. If you do not have a result URL and you do not know whether the server finished, do not immediately send the same prompt again. Check the request ID and the 免费额度 remainder first.

A few other knobs change quality or latency, not the per-image count, and are still not worth extra trial calls on a 10-image grant. prompt_extend defaults to true. prompt_extend_mode=agent is documented for text-to-image only; sending it on an edit returns 400. enable_thinking defaults to true and is documented to help quality at the cost of time, and only when prompt rewriting is on. negative_prompt exists on the 3.0 series and not on 2.1. watermark defaults to false. The Beijing rate limit on the model page is 20 requests per minute. The error catalog also notes that some image models, including qwen-image-3.0-pro, do not support asynchronous calls; setting X-DashScope-Async: enable can return 429 even on a single request.

If the grant is gone and the stop switch is off, the Beijing list prices above apply. That is the outcome this page is written to avoid.

When is this the wrong API?

Skip this walkthrough if the console shows no remaining grant for qwen-image-3.0, or if you already know you need a dozen variations. The free allowance is too small for prompt fishing.

It is also the wrong interface if you need OpenAI’s /images/edits multipart protocol, a mask, streamed partial images, asynchronous OpenAI-compatible calls, or a Base64 payload in the response. Those are documented gaps. If you need to hold the HTTP connection open for a batch, the docs point at DashScope asynchronous mode, not at the path used here.

Choose a different Model Studio model if the job is outside this grant and this resolution. The official image-model guide points at qwen-image-3.0-pro for dense typography and complex layouts, at Wan 2.7 when you need higher than 2048×2048 on text-to-image, and at qwen-image-2.1-pro or qwen-image-2.1-turbo when you must send more than three reference images. Those are other pages. This one stays on two calls against the standard 3.0 grant.

If your account already lives on the international site, the Singapore grant and USD prices are the ones that apply, and the English API samples are written for that region. This tutorial does not walk that path, because the steps above are meant to be finished from mainland China on aliyun.com.

What still has to be checked on a live key

A later revision should replace the unverified banner with the run date, the SDK version, the two request IDs, the documented usage objects as actually returned, and the two saved PNGs from that run. It should also confirm whether the first result URL is accepted as the edit image value, how quickly the 免费额度 remainder updates after three images, and whether a first-time China-site activation on or after 17 November 2026 still receives the 10-image grant for this model.

Until that run exists, treat every command on this page as planned.

Sources

  • 模型调用价格: Beijing grant wording 输入输出共 10张 for qwen-image-3.0 and qwen-image-3.0-pro; input CNY 0.02 per image; output CNY 0.18 for qwen-image-3.0 at 1K and 2K; Pro output CNY 0.25 / 0.50; 2.1 series output prices and 10-image grants; failed requests do not consume the grant; free grants only in Beijing on the China site.
  • 新人免费额度: 90-day clock, 实名认证, Beijing-only grants on the China site, stop-when-exhausted off by default, HTTP 403 with AllocationQuota.FreeTierOnly, console remainder, Token Plan keys, and the warning about image models on a Token Plan text base URL.
  • 模型上架与更新: qwen-image-3.0-pro listed on 2026-07-20; qwen-image-3.0 listed on 2026-08-04.
  • 千问-图像生成与编辑 API参考: shared /images/generations endpoint, Beijing workspace and legacy hosts, parameters, size separator, documented response, 24-hour URL, 600-second timeout, and the note that English samples are for a different region.
  • qwen-image-3.0 模型信息: Beijing list prices and a 20 RPM limit.
  • 图片生成与编辑: when official docs recommend 3.0, 3.0-pro, Wan 2.7, or Z-Image, and the 6-image / 2048×2048 caps.
  • 获取与配置 API Key: creating a key in the Beijing console, and the legacy dashscope host the tools section still shows.
  • 错误码: AllocationQuota.FreeTierOnly, region-mismatched keys, InvalidParameter, DataInspectionFailed, and the 429 note about X-DashScope-Async on some image models.
  • Model inference pricing (international site, retrieved the same day): 10-image grant listed in Singapore only; Beijing shown as paid USD prices with no grant column.

Earlier tutorials in this cluster cover hosted text models on the same China-site Beijing path. They are not required reading for these two image calls, and this page does not depend on their scripts.


Title tag: Call Qwen Image 3.0 on the 10-Image Free Quota for a Shot and an Edit

Meta description: On Alibaba Model Studio’s China site in Beijing, qwen-image-3.0 has a 10-image free grant that counts inputs and outputs together. Turn on stop-when-exhausted, then run one product-style text-to-image call and one edit. From official docs; not yet run.

Slug: qwen-image-3.0-free-quota-text-to-image-edit

Evidence it actually ran

This is the shape of the stamp. It has not been earned, and the example date that follows is a placeholder, not a run: Ran on YYYY-MM-DD (Asia/Shanghai) with the pinned versions.

Command output
None recorded. A verified revision will quote the output from the run, not a sample written in advance.
Tests, CI, or Inspector
Not run for this draft.
Repository or config
No link recorded.

Failure modes

Anticipated only. None of these has been checked against a run of this tutorial.

  • Unchecked

    The edit is sent to /images/edits instead of /images/generations

    For qwen-image-3.0 the documented edit path is the same OpenAI-compatible /images/generations method, with the source image in extra_body["image"]. /images/edits is the wrong interface for this model.

  • Unchecked

    A client timeout is retried and spends extra images

    Official docs say a failed request does not consume the grant, but a client timeout or a killed process is not the same as a documented failure. If you do not have a result URL and you do not know whether the server finished, check the request ID and the 免费额度 remainder before sending the same prompt again.

  • Unchecked

    prompt_extend_mode=agent is sent on an edit

    prompt_extend_mode=agent is documented for text-to-image only; sending it on an edit returns 400.

  • Unchecked

    n is raised to compare compositions

    n can be 1 through 6, and every successful image counts. Raising it is the fastest way to turn a two-call job into a six- or twelve-image job on a 10-image grant.

  • Unchecked

    Result URLs expire before the PNGs are saved

    Official docs say result links last 24 hours and are then cleared. The script writes them to examples/out/mug-t2i.png and examples/out/mug-edit.png as soon as each URL comes back.

  • Unchecked

    401 from a key and host in different regions

    A Beijing key pointed at a Singapore URL is a documented 401 mismatch. The key, the host, and the model have to be in one region.

  • Unchecked

    The grant is gone and the stop switch is off

    If the grant is exhausted and 免费额度用完即停 is off, later calls flip to the published Beijing list prices. That is the outcome this page is written to avoid.

Other tutorials in Integrate.