Qwen Image 3.0 Image Generation
Generate images with qwen-image-3.0 or qwen-image-3.0-pro
Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.
- Supports
qwen-image-3.0andqwen-image-3.0-pro - Supports text-to-image, image-to-image, and multi-reference generation
- Accepts up to 3 reference images
- Supports 1K and 2K output resolutions with 7 aspect ratios
- Generates exactly 1 image per request.
nmust be1 - Runs asynchronously and returns a task ID for status queries
image_urls accepts publicly accessible image URLs only. Base64 Data URIs are not supported. Use the Upload Image API first for local files.
Supported models
| Model | Text-to-image | Image-to-image | Reference limit | Output |
|---|---|---|---|---|
qwen-image-3.0 | Yes | Yes | 3 images | Exactly 1 |
qwen-image-3.0-pro | Yes | Yes | 3 images | Exactly 1 |
Authorizations
AuthorizationstringheaderrequiredAll endpoints require Bearer Token authentication.
Get an API key from the API Key Management Page and send it in the request header:
Authorization: Bearer YOUR_API_KEYBody
modelstringbodyrequiredModel name. The only supported values are:
qwen-image-3.0qwen-image-3.0-pro
promptstringbodyrequiredText description or editing instruction. The value cannot be empty.
sizestringbodyOutput aspect ratio. Recommended values:
1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3
Explicit pixel sizes are also accepted as WIDTH*HEIGHT or WIDTHxHEIGHT. The total pixel area must be between 512*512 and 2048*2048, and the aspect ratio must be between 1:8 and 8:1.
If omitted, the model chooses the output size.
resolutionstringbodydefault: 1KResolution tier used when size is an aspect ratio:
1K- Default2K
metadata.resolution is also accepted, but the top-level field is recommended.
nintegerbodydefault: 1Number of images to generate. This is fixed at 1.
Values greater than 1 return 400 invalid_request.
image_urlsstring[]bodyReference image URLs for image-to-image, editing, or multi-reference generation.
- Maximum 3 images
- URLs only; base64 Data URIs are not supported
- Use the Upload Image API for local files
client_business_idstringbodyYour order ID, transaction ID, or other business identifier. When provided, the same image task endpoint can be queried with this ID.
metadataobjectbodyQwen Image advanced parameters.
metadata properties
metadata.prompt_extendbooleanbodydefault: trueWhether to automatically optimize and expand the prompt.
metadata.prompt_extend_modestringbodyPrompt expansion mode:
direct- Direct expansionagent- Agent expansion, text-to-image only
When image_urls is present, agent is automatically changed to direct.
metadata.negative_promptstringbodyNegative prompt describing content to avoid.
metadata.seedintegerbodyRandom seed. The same seed can help produce similar results, but does not guarantee identical output.
metadata.watermarkbooleanbodydefault: falseWhether to add a watermark.
Resolution and pixel mapping
When size is an aspect ratio, ToAPIs maps it to the following pixel dimensions. Both models use the same mapping.
| Aspect ratio | 1K | 2K |
|---|---|---|
1:1 | 1024×1024 | 2048×2048 |
4:3 | 1152×864 | 1600×1200 |
3:4 | 864×1152 | 1200×1600 |
16:9 | 1280×720 | 1920×1080 |
9:16 | 720×1280 | 1080×1920 |
3:2 | 1152×768 | 1728×1152 |
2:3 | 768×1152 | 1152×1728 |
Response
idstringUnique task identifier for status queries.
objectstringObject type, always generation.task.
modelstringModel used for the request.
statusstringTask status: queued, in_progress, completed, or failed.
progressintegerProgress percentage from 0 to 100.
created_atintegerTask creation time as a Unix timestamp.
Request examples
requestExample
curl --request POST \
--url https://toapis.com/v1/images/generations \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen-image-3.0",
"prompt": "A cinematic fantasy poster of an ancient city above the clouds, golden morning light, with the clear Chinese title 云上长安",
"size": "16:9",
"resolution": "2K",
"n": 1,
"metadata": {
"prompt_extend": true,
"negative_prompt": "blurry, low quality, incorrect text",
"watermark": false
}
}'curl --request POST \
--url https://toapis.com/v1/images/generations \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"model": "qwen-image-3.0-pro",
"prompt": "Keep the person from the first image and the clothing design from the second image. Create a modern magazine cover with detailed facial features and materials.",
"image_urls": [
"https://example.com/person.png",
"https://example.com/outfit.png"
],
"size": "3:4",
"resolution": "2K",
"n": 1,
"metadata": {
"prompt_extend": true,
"prompt_extend_mode": "direct",
"watermark": false
}
}'import requests
response = requests.post(
"https://toapis.com/v1/images/generations",
headers={
"Authorization": "Bearer <YOUR_API_KEY>",
"Content-Type": "application/json",
},
json={
"model": "qwen-image-3.0-pro",
"prompt": "A premium black-and-gold perfume poster with studio lighting and sharp details",
"size": "1:1",
"resolution": "2K",
"n": 1,
"metadata": {
"prompt_extend": True,
"watermark": False,
},
},
)
response.raise_for_status()
task = response.json()
print(task["id"], task["status"])const response = await fetch("https://toapis.com/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <YOUR_API_KEY>",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "qwen-image-3.0",
prompt: "A cinematic product photo of a transparent mechanical watch",
size: "4:3",
resolution: "1K",
n: 1,
metadata: {
prompt_extend: true,
watermark: false
}
})
});
if (!response.ok) {
throw new Error(await response.text());
}
const task = await response.json();
console.log(task.id, task.status);Submission response
{
"id": "task_img_abc123def456",
"object": "generation.task",
"model": "qwen-image-3.0-pro",
"status": "queued",
"progress": 0,
"created_at": 1787270400
}Query the task
curl --request GET \
--url https://toapis.com/v1/images/generations/task_img_abc123def456 \
--header 'Authorization: Bearer <YOUR_API_KEY>'See Get Image Task Status for response fields and polling guidance.
Completed response
{
"id": "task_img_abc123def456",
"object": "generation.task",
"model": "qwen-image-3.0-pro",
"status": "completed",
"progress": 100,
"created_at": 1787270400,
"completed_at": 1787270458,
"expires_at": 1789862458,
"result": {
"type": "image",
"data": [
{
"url": "https://files.toapis.com/generated/qwen-image-result.png"
}
]
}
}Generated images are retained for 30 days. Download or copy the image before expires_at.
Billing
- Successful output:
$0.03per request - Reference image input:
$0.003per image - There is no free reference-image allowance
qwen-image-3.0andqwen-image-3.0-procurrently use the same billing rules