Text-to-image

• Wan: Photorealistic imagery with text rendering, brand color control, and image editing.
• Z-Image: Fast, low-cost generation optimized for realistic portraits and product shots.
• Qwen-Image: Excels at rendering complex Chinese and English text.

​

Model performance

​

Qwen-Image

Complex text	Long paragraphs	Complex layouts
Poster creation	Illustration design	Realistic photography

​

Wan series

Portrait photography	Realistic photography	Painting styles
Text generation	Poster design	Image set generation

​

Model availability

​

Getting started

​

Prerequisites

​

Sample code

import json
import os
import dashscope
from dashscope import MultiModalConversation

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

messages = [
  {
    "role": "user",
    "content": [
      {"text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title \"Come Play Ball!\" is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle \"Come [Show Off Your Skills]!\" appears in green font. A speech bubble adds playful charm with the text: \"Hehe, watch me amaze my little friends next!\" At the bottom, supplementary text reads: \"We get to play ball with our friends again!\" The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."}
    ]
  }
]

# If you haven't set the environment variable, replace the line below with: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

response = MultiModalConversation.call(
  api_key=api_key,
  model="qwen-image-2.0-pro",
  messages=messages,
  result_format='message',
  stream=False,
  watermark=False,
  prompt_extend=True,
  negative_prompt="Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.",
  size='2048*2048'
)

if response.status_code == 200:
  print(json.dumps(response, ensure_ascii=False))
else:
  print(f"HTTP status code: {response.status_code}")
  print(f"Error code: {response.code}")
  print(f"Error message: {response.message}")

{
  "status_code": 200,
  "request_id": "d2d1a8c0-325f-9b9d-8b90-xxxxxx",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "image": "https://dashscope-result-intl.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "width": 2048,
    "image_count": 1,
    "height": 2048
  }
}

import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If you have not configured the environment variable, replace the following line with your API key: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")


def main():
  message = Message(
    role="user",
    content=[
      {
        "text": "A young woman taking a casual selfie outdoors, natural lighting, warm tones, soft bokeh background with greenery"
      }
    ]
  )

  # Submit async task
  print("Submitting async task...")
  response = ImageGeneration.async_call(
    model="wan2.7-image-pro",
    api_key=api_key,
    messages=[message],
    enable_sequential=False,
    n=1,
    size="2K"
  )

  if response.status_code == 200:
    print(f"Task submitted, task ID: {response.output.task_id}")

    # Wait for task completion
    status = ImageGeneration.wait(task=response, api_key=api_key)

    if status.output.task_status == "SUCCEEDED":
      print("Task completed!")
      print(status)
    else:
      print(f"Task failed, status: {status.output.task_status}")
  else:
    print(f"Task creation failed: {response.code} - {response.message}")


if __name__ == "__main__":
  try:
    main()
  except Exception as e:
    print(f"Error: {e}")

{
  "output": {
    "task_status": "PENDING",
    "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
  },
  "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

{
  "status_code": 200,
  "request_id": "56e318fd-ed60-99e8-8ca1-cdef25ca4xxx",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "image": "https://dashscope-result-intl.oss-cn-shanghai.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
              "type": "image"
            }
          ]
        }
      }
    ],
    "audio": null,
    "task_id": "77093787-a217-4c29-9cd4-ca7b5ac86xxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2026-03-31 23:04:46.166",
    "scheduled_time": "2026-03-31 23:04:46.208",
    "end_time": "2026-03-31 23:05:11.664",
    "finished": true
  },
  "usage": {
    "input_tokens": 720,
    "output_tokens": 11,
    "characters": 0,
    "size": "2048*2048",
    "total_tokens": 731,
    "image_count": 1
  }
}

​

Key capabilities

​

Instruction following

• Prompt (required): Describes the desired content, style, and composition. Pass the prompt in the following format:
  • Qwen-Image, Wan 2.7, and wan2.6-t2i: Use input.messages[].content[].text. See the sample code in the corresponding tab under Sample code.
  • Wan 2.5 and earlier: Use input.prompt.
• negative_prompt (optional): Describes elements to exclude from the image, such as "blurry" or "extra fingers". Set via parameters.negative_prompt. Supported by all models except wan2.7-image-pro and wan2.7-image.

​

Enable prompt rewriting

• Enable when your prompt is simple or broad — this can significantly improve quality.
• Disable (false) when you need fine-grained control, have already written a detailed prompt, or are sensitive to latency.

​

Set the output image resolution

• 4K: wan2.7-image-pro only.
• 2K: wan2.7-image-pro, wan2.7-image, qwen-image-2.0 series.
• 1K: Wan t2i models.

​

Set the number of images

​

Wan 2.7 parameters

• enable_sequential (bool, default: false): Enables image set generation. When true, you can generate 1-12 coherent images per request by setting n between 1 and 12.
  When enable_sequential is set to true, thinking_mode and color_palette are unavailable.
• thinking_mode (bool, default: true): Enables enhanced reasoning for better prompt understanding and image quality. Only available when enable_sequential is false.
• color_palette (array): Defines a custom color theme. Specify 3-10 colors (8 recommended), each with a hex value and a ratio (percentage string). Ratios must sum to 100%. Only available when enable_sequential is false.

"color_palette": [
  {"hex": "#C2D1E6", "ratio": "23.51%"},
  {"hex": "#CDD8E9", "ratio": "20.13%"},
  {"hex": "#B5C8DB", "ratio": "15.88%"},
  {"hex": "#C0B5B4", "ratio": "13.27%"},
  {"hex": "#DAE0EC", "ratio": "10.11%"},
  {"hex": "#636574", "ratio": "8.93%"},
  {"hex": "#CACAD2", "ratio": "5.55%"},
  {"hex": "#CBD4E4", "ratio": "2.62%"}
]

​

Going live

​

Fault tolerance

• Rate limits: A Throttling error code or HTTP 429 means rate limiting is active. See Rate limits.
• Async task polling: Poll every 3 seconds for the first 30 seconds, then increase the interval. Set a final timeout (e.g. 2 minutes) and treat the task as failed if it expires.

​

Risk prevention

• Result persistence: Image URLs expire after 24 hours. Download and store images in your own storage (e.g. OSS) immediately after retrieval.
• Content moderation: All prompt and negative_prompt inputs are moderated. Non-compliant input is blocked with a DataInspectionFailed error.
• Copyright and compliance: Prompts that reference brand trademarks, celebrity likenesses, or copyrighted IP may pose infringement risks. You are responsible for any resulting liabilities.

​

API reference

• Qwen - Synchronous
• Z-Image
• Wan 2.7 - Image generation & editing
• Wan 2.6 - Image generation & editing
• Wan - text-to-image V2

​

Error codes

​

FAQ