How to Use the Qwen Image 3 Pro API via DashScope: A Developer Tutorial

Alibaba's qwen-image-3.0-pro is the flagship image-generation model served through Model Studio, also known as DashScope or Bailian. It targets backend developers who need a reliable text-to-image endpoint with predictable pricing. The official model ID qwen-image-3.0-pro is documented in Alibaba's Model Studio catalog (Alibaba Cloud Model Studio docs, 2026), and you can call it from any HTTP client.

This tutorial walks through the full integration. By the end, you will have an API key, a working cURL call, a Python snippet, and a clear view of the per-image cost structure.

Key Takeaways

• Model ID: qwen-image-3.0-pro, served on Alibaba Cloud Model Studio / DashScope at https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026).
• Auth: set DASHSCOPE_API_KEY as an environment variable, then send it as a Bearer token (Promptfoo, 2026).
• Reference price: the predecessor qwen-image-2.0-pro costs $0.075 per generated image on Alibaba official pricing (Alibaba Cloud pricing, 2026).
• Each image model has a free quota for testing before you pay a cent (Alibaba Image API FAQ, 2026).

Prerequisites

Before you write any code, confirm you have an Alibaba Cloud account with Model Studio access. The official "First API call to Qwen" guide lists three things every developer needs: an API Key generated in the Model Studio console, a Workspace ID tied to your project, and access to the DashScope HTTP endpoint (Alibaba Cloud, 2026).

You also need basic tooling. A terminal with cURL, Python 3.9 or newer, and the requests library cover everything in this tutorial. No proprietary SDK is required. If you have ever called the OpenAI API from a script, the DashScope pattern will feel familiar, since both use Bearer tokens and JSON request bodies.

A recommended pattern is to keep one dedicated Workspace per environment, so staging keys never touch production quotas. This separation also makes cost attribution cleaner at the end of the month.

Step 1: Get Your API Key and Workspace ID

The API Key is the credential that authorizes every call you make to qwen-image-3.0-pro. Alibaba's getting-started guide instructs developers to create the key inside the Model Studio console and then copy the Workspace ID from the same dashboard (Alibaba Cloud, 2026). Treat both values as secrets.

To retrieve them:

1. Sign in to the Model Studio console at the Alibaba Cloud portal.
2. Open the API Keys section and click Create API Key.
3. Copy the generated key immediately. The console hides the full value after creation.
4. Note the Workspace ID displayed at the top of the dashboard.

Store the key in a password manager or your team's secret backend. Do not paste it into source files. The Workspace ID is less sensitive but still worth keeping in configuration rather than inline.

Citation capsule: Alibaba's official "First API call to Qwen" guide instructs developers to create an API Key in the Model Studio console, copy the Workspace ID from the same dashboard, and call models via the DashScope endpoint at https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026).

Step 2: Set the DASHSCOPE_API_KEY Environment Variable

Loading the key into an environment variable keeps it out of your code and out of version control. The community pattern documented by Promptfoo is to set a variable named DASHSCOPE_API_KEY before running your script, which is then read by the HTTP client at request time (Promptfoo, 2026).

On macOS and Linux:

export DASHSCOPE_API_KEY="sk-your-key-here"

On Windows PowerShell:

$env:DASHSCOPE_API_KEY = "sk-your-key-here"

For a permanent setup, add the export line to your ~/.zshrc, ~/.bashrc, or Windows user environment variables. Restart your terminal afterward. Verify the variable is loaded before moving on:

echo $DASHSCOPE_API_KEY

A common setup is a .env file plus a loader like python-dotenv, so the same configuration works across local development, CI, and container deployments. Remember to add .env to .gitignore so the key never gets committed.

Step 3: Make Your First Image Generation Call with cURL

The DashScope endpoint at https://dashscope-us.aliyuncs.com/api/v1 is the entry point for every Qwen model, including qwen-image-3.0-pro (Alibaba Cloud, 2026). Calls use a Bearer token in the Authorization header and a JSON body that names the model plus your prompt.

Below is an illustrative cURL request based on the documented endpoint and auth pattern. Field names and exact request paths follow the DashScope convention, but you should confirm the current schema against the official API reference at Qwen API via DashScope before shipping to production.

# Illustrative example. Confirm exact field names and paths against:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
curl -X POST "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "input": {
      "prompt": "A cozy bookstore cafe in autumn, warm light, highly detailed"
    },
    "parameters": {
      "size": "1024*1024",
      "n": 1
    }
  }'

A few practical notes:

• Some DashScope image endpoints are asynchronous, meaning the first response returns a task ID, and you poll a second URL to fetch the finished image. Check the API reference for the exact behavior of qwen-image-3.0-pro.
• Keep prompts under the documented token limit. Long prompts can truncate silently.
• Use the size parameter matching one of the supported aspect ratios, otherwise the call may fall back to a default.

Citation capsule: The official DashScope endpoint at https://dashscope-us.aliyuncs.com/api/v1 serves qwen-image-3.0-pro, with full input and output parameter reference documented by Alibaba Cloud (Alibaba Cloud, 2026).

Step 4: Parse the Response in Python

Python is the most common language for wrapping image APIs because the requests library makes JSON parsing trivial. Once the call returns, you extract the generated image URL, download it, and persist it to disk or object storage.

Here is a short illustrative script. As with cURL, confirm the response field names against the official API reference before relying on them.

# Illustrative example. Confirm response schema against:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
ENDPOINT = "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "qwen-image-3.0-pro",
    "input": {
        "prompt": "A cozy bookstore cafe in autumn, warm light, highly detailed"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}

response = requests.post(ENDPOINT, headers=headers, json=payload)
response.raise_for_status()
data = response.json()

# Field names below are illustrative. Verify against the official API reference.
image_url = data["output"]["results"][0]["url"]
print("Generated image URL:", image_url)

# Download the file
img = requests.get(image_url)
with open("output.png", "wb") as f:
    f.write(img.content)

A few production-grade tips:

• Wrap the call in retry with exponential backoff. Network blips happen.
• Add a timeout. Image generation can take several seconds.
• Log the full request ID, usually returned in a response header, so Alibaba support can trace failures.

It helps to add a thin abstraction layer between the API client and business logic. That way, swapping models later (say to an edit endpoint or a newer Qwen release) only changes one module.

How Much Does Qwen Image 3 Pro Cost?

Pricing is per generated image, and Alibaba only bills you for successful generations. The official pricing page lists qwen-image-2.0-pro at $0.075 per image (Alibaba Cloud pricing, 2026). Third-party providers offer Qwen image models at different price points: Fal lists a Qwen image model at roughly $0.021 per image, and Replicate charges about $0.030 per image at 1024x1024 (Puter pricing breakdown, 2026; pricepertoken, 2026).

For qwen-image-3.0-pro specifically, treat the 2.0-pro price as the closest official reference, then verify the current figure on the Model Studio pricing page before budgeting.

Citation capsule: Alibaba's Model Studio prices qwen-image-2.0-pro at $0.075 per generated image, billing only successful generations, while third-party providers such as Fal and Replicate list Qwen image models at approximately $0.021 and $0.030 per image respectively (Alibaba Cloud, 2026; Puter, 2026).

A rough monthly budget for a small app might look like this:

Prices as of July 2026.

Free Quota and Limits

Every image model on Model Studio ships with a free quota, so you can test before you commit spend (Alibaba Image API FAQ, 2026). The quota resets on a schedule documented in the FAQ.

A few practical pointers:

• Use the free quota to validate prompt templates and parameter combinations.
• Monitor usage in the Model Studio dashboard to avoid surprise bills once you switch to paid tiers.
• If your tests suddenly start failing with quota errors, double-check whether the free tier expired or whether you switched Workspaces.

Beyond Text-to-Image: The Edit API

The Qwen family also includes a dedicated image-editing endpoint. It supports multi-image input and output, in-image text editing, object addition, removal and movement, and pose changes (Qwen-Image Edit API, 2026).

This matters because edit calls use a different request shape from text-to-image calls. If your product needs background swap or object removal, you will be hitting a separate endpoint with its own parameters and pricing. Plan for two integration tracks: one for generation, one for editing.

FAQ

What is the model ID for Qwen Image 3 Pro?

The official model ID is qwen-image-3.0-pro, served on Alibaba Cloud Model Studio / DashScope at https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026). Use this exact string in the model field of your request body.

How do I authenticate DashScope API calls?

Set the DASHSCOPE_API_KEY environment variable, then send it as a Bearer token in the Authorization header of every request (Promptfoo, 2026). Never hardcode the key in source files or commit it to version control.

How much does Qwen Image 3 Pro cost per image?

Alibaba prices the predecessor qwen-image-2.0-pro at $0.075 per image and bills only successful generations (Alibaba Cloud pricing, 2026). Third-party providers such as Fal and Replicate list Qwen image models at roughly $0.021 and $0.030 per image. Verify current 3.0-pro pricing on the official page.

Is there a free quota?

Yes. Each image model on Model Studio has a free quota you can use for testing before paid billing kicks in (Alibaba Image API FAQ, 2026). Check the FAQ for reset cadence and limits, which vary by model.

Does Qwen Image 3 Pro support image editing?

Editing is handled by a separate endpoint called Qwen-Image Edit, which supports multi-image IO, text editing inside images, object add, remove and move, and pose changes (Qwen-Image Edit API, 2026). The text-to-image and edit APIs have different request shapes.

Conclusion

You now have the full path to your first qwen-image-3.0-pro call: an API Key from the Model Studio console, the DASHSCOPE_API_KEY environment variable loaded, a working cURL request, and a Python snippet that parses and downloads the result. The per-image pricing model, starting from $0.075 on Alibaba official pricing, makes cost predictable as you scale.

Two next steps will sharpen your integration. First, confirm the exact request and response field names against the official API reference at Qwen API via DashScope, since schema details can shift between model versions. Second, if your product needs edits rather than pure generation, explore the Qwen-Image Edit API, which unlocks object removal, text editing, and pose changes through a dedicated endpoint.

Build small, watch your quota, and ship.