Text-to-Image API Guide: Create AI Images with Wan and Qwen-Image Models

The text-to-image API lets developers create entirely new images from written descriptions. Alibaba Cloud Model Studio (Bailian) offers the Wan (万相), Qwen-Image (千问) and z-image model families, making it straightforward to add AI image generation to websites, design tools, marketing workflows and creative apps. This guide explains how to get started, choose a suitable model, control output quality, and prepare the integration for production use.

Before writing any code, you can test generation in the web-based Experience Center, available in the Beijing and Singapore regions. Enter a text description, choose a model, set the output resolution, toggle smart rewriting, and submit. The Tongyi Wanxiang standalone site also offers direct image generation. When you are ready to embed the capability in your own product, switch to the API calls described below.

Model Studio currently recommends three Qwen-Image options. qwen-image-3.0-pro delivers flagship quality, supports intelligent prompt rewriting, and excels at accurate Chinese and English text rendering with realistic materials. qwen-image-2.1-pro balances speed, quality and cost, and supports up to ten reference images for image-to-image tasks. It can automatically output either standard images or images with transparency depending on the prompt. qwen-image-2.1-turbo offers the best cost-performance ratio in the series and shares the same reference-image and transparency capabilities. Select the model that matches your quality target, latency tolerance and budget.

Before calling the API, obtain an API key and set it as an environment variable. If you use the DashScope SDK, install it first. The example below uses synchronous calling with the qwen-image-3.0-pro model through MultiModalConversation. The response contains an image URL that can be retrieved from the output. Qwen-Image also supports asynchronous calling, and Wan models have their own API references. Check the response status code and handle errors using the returned code and message fields.

The positive prompt (text in messages or prompt in input) is the core control parameter. Describe the subject, scene, style, lighting and composition you want. The optional negative_prompt describes unwanted elements such as blur or extra fingers. Note that wan2.7-image-pro, wan2.7-image and qwen-image-2.1 series do not accept negative_prompt, so express exclusions directly in the positive prompt. Text rendering inside images works for short titles and phrases, but long passages or full poems may contain typos or missing characters. For critical text, keep it short or edit the result afterward. Prompt rewriting, enabled with prompt_extend, expands short or vague prompts and typically adds three to five seconds of latency. Keep it on for concise inputs and turn it off when your prompt is already detailed or when latency is critical. Qwen-Image 3.0 and 2.1 series also accept prompt_extend_mode, where direct is suitable for most scenarios and agent offers finer rewriting for text-to-image only.

Set the output size with the size parameter in the format width*height. Qwen-Image 3.0 and 2.1 series accept sizes from 512x512 to 2048x2048 with aspect ratios between 1:8 and 8:1, and the model picks a recommended size if none is specified. Qwen-Image 2.0 defaults to 2048x2048. wan2.7-image-pro supports 1K, 2K and 4K presets or custom sizes from 768x768 to 4096x4096, with 2K as the default. The 4K and custom 4096x4096 options are available only for text-to-image requests without image inputs or sequential generation. wan2.7-image supports 1K and 2K presets or custom sizes up to 2048x2048. Recommended pixel sizes include 2048x2048 for square 2K, 2688x1536 for 16:9 at 2K, and 4096x2304 for 16:9 at 4K. For storytelling or consistent series, enable sequential generation with enable_sequential set to true. The n parameter controls how many images are produced, from 1 to 12 in set mode. Billing is based on the number of successfully generated images, so n directly affects cost.

For wan2.7-image-pro and wan2.7-image, thinking_mode (enabled by default) strengthens reasoning to improve output quality at the cost of additional generation time. This setting can replace prompt_extend for these models, which do not support that parameter. Custom color palettes are available through color_palette, where you provide between three and ten colors in hex format, each with a ratio, and the ratios must total 100 percent. The recommended palette size is eight colors. Note that thinking_mode and color_palette cannot be used together with sequential image set generation.

Several general parameters help you control repeatability and presentation. seed accepts an integer between 0 and 2147483647, and reusing the same seed produces relatively stable results. If no seed is provided, the service chooses one randomly. watermark, which defaults to false, adds an AI-generated label to the bottom-right corner of the image when enabled. The n parameter sets the number of images, as described earlier. Check each model's API reference to confirm which parameters are supported.

Production systems need robust handling. When the API returns a Throttling error code or HTTP 429, apply rate-limit handling as described in the rate-limit documentation. For asynchronous tasks, poll results with a sensible strategy, such as checking every three seconds for the first thirty seconds and then increasing the interval, and set a final timeout, for example two minutes, after which the task is marked failed. Image URLs expire after 24 hours, so download each image immediately and store it in persistent storage such as Alibaba Cloud Object Storage Service (OSS). All prompts and negative prompts pass content safety review, and non-compliant inputs return a DataInspectionFailed error. Ensure your prompts comply with applicable laws, and carefully evaluate copyright and portrait-rights risks before generating brand logos, celebrity likenesses or protected characters.

Image URLs remain valid for 24 hours, so save them permanently right after generation. If a request fails with DataInspectionFailed, revise the prompt to remove potentially non-compliant content and retry. For prompt_extend, keep it enabled for brief prompts or when creative variation is welcome, and set it explicitly to false for detailed prompts or strict latency requirements. Models that do not support prompt_extend can use thinking_mode instead. To clear the conversation in the Experience Center, click the clear control at the top right of the console. For any other model error, consult the error code reference and the official API documentation.