ToAPIsToAPIs
Qwen Image 3.0

Qwen Image 3.0 Image Generation

Generate images with qwen-image-3.0 or qwen-image-3.0-pro

POST
/v1/images/generations

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.0 and qwen-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. n must be 1
  • 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

ModelText-to-imageImage-to-imageReference limitOutput
qwen-image-3.0YesYes3 imagesExactly 1
qwen-image-3.0-proYesYes3 imagesExactly 1

Authorizations

Authorizationstringheaderrequired

All 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_KEY

Body

modelstringbodyrequired

Model name. The only supported values are:

  • qwen-image-3.0
  • qwen-image-3.0-pro
promptstringbodyrequired

Text description or editing instruction. The value cannot be empty.

sizestringbody

Output 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: 1K

Resolution tier used when size is an aspect ratio:

  • 1K - Default
  • 2K

metadata.resolution is also accepted, but the top-level field is recommended.

nintegerbodydefault: 1

Number of images to generate. This is fixed at 1.

Values greater than 1 return 400 invalid_request.

image_urlsstring[]body

Reference 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_idstringbody

Your order ID, transaction ID, or other business identifier. When provided, the same image task endpoint can be queried with this ID.

metadataobjectbody

Qwen Image advanced parameters.

metadata properties
metadata.prompt_extendbooleanbodydefault: true

Whether to automatically optimize and expand the prompt.

metadata.prompt_extend_modestringbody

Prompt expansion mode:

  • direct - Direct expansion
  • agent - Agent expansion, text-to-image only

When image_urls is present, agent is automatically changed to direct.

metadata.negative_promptstringbody

Negative prompt describing content to avoid.

metadata.seedintegerbody

Random seed. The same seed can help produce similar results, but does not guarantee identical output.

metadata.watermarkbooleanbodydefault: false

Whether 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 ratio1K2K
1:11024×10242048×2048
4:31152×8641600×1200
3:4864×11521200×1600
16:91280×7201920×1080
9:16720×12801080×1920
3:21152×7681728×1152
2:3768×11521152×1728

Response

idstring

Unique task identifier for status queries.

objectstring

Object type, always generation.task.

modelstring

Model used for the request.

statusstring

Task status: queued, in_progress, completed, or failed.

progressinteger

Progress percentage from 0 to 100.

created_atinteger

Task 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.03 per request
  • Reference image input: $0.003 per image
  • There is no free reference-image allowance
  • qwen-image-3.0 and qwen-image-3.0-pro currently use the same billing rules