Z-Image | Qwen Cloud

POST

/services/aigc/multimodal-generation/generation

cURL

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
  "model": "z-image-turbo",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "text": "A sitting orange cat with a happy expression, lively and cute, realistic and accurate"
          }
        ]
      }
    ]
  },
  "parameters": {
    "prompt_extend": false,
    "size": "1024*1024"
  }
}'

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "image": "https://dashscope-result-sgp.oss-ap-southeast-1.aliyuncs.com/xxx.png?Expires=xxx"
            },
            {
              "text": "Photo of a stylish young woman..."
            }
          ],
          "reasoning_content": ""
        }
      }
    ]
  },
  "usage": {
    "width": 1024,
    "height": 1024,
    "image_count": 1,
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  },
  "request_id": "abf1645b-b630-433a-92f6-xxxxxx"
}

Get an API key and set it as an environment variable. If using the SDK, install it.

Z-Image is a lightweight text-to-image model that generates images quickly. It renders Chinese and English text and adapts to various resolutions and aspect ratios. Quick links: Try it online | Technical blog

Authorizations

string

header

required

DashScope API key. Create one in the Qwen Cloud console. Alternatively, pass it via the X-DashScope-ApiKey request header.

Body

application/json

enum<string>

required

Model name.

Available options:z-image-turbo

Example:z-image-turbo

object

required

Input content.

Show child attributes

object[]

required

Request content array. Single-turn only — pass one message with role: user. Multi-turn is not supported.

Required range:items: 1–1

Show child attributes

enum<string>

required

Message role. Must be user.

Available options:user

object[]

required

Message content array. Must contain exactly one text object. Passing zero or multiple text objects returns an error.

Show child attributes

string

Positive prompt describing desired content, style, and composition. Supports Chinese and English. Max 800 characters (each character, letter, number, or symbol counts as one). Extra characters are truncated.

Example:A sitting orange cat with a happy expression, lively and cute, realistic and accurate

Required range:length <= 800

object

Image generation parameters.

Show child attributes

string

default"1024*1536"

Output image resolution as width*height. Range: 512×512 to 2048×2048 pixels. Recommended range: 1024×1024 to 1536×1536. Default: 1024*1536.

Recommended resolutions (1024×1024 total pixels): 1024*1024 (1:1), 832*1248 (2:3), 1248*832 (3:2), 864*1152 (3:4), 1152*864 (4:3), 720*1280 (9:16), 1280*720 (16:9).

Recommended resolutions (1280×1280 total pixels): 1280*1280 (1:1), 1024*1536 (2:3), 1536*1024 (3:2), 1104*1472 (3:4), 1472*1104 (4:3), 864*1536 (9:16), 1536*864 (16:9).

Recommended resolutions (1536×1536 total pixels): 1536*1536 (1:1), 1248*1872 (2:3), 1872*1248 (3:2), 1296*1728 (3:4), 1728*1296 (4:3), 1152*2048 (9:16), 2048*1152 (16:9).

Example:1024*1024

boolean

defaultfalse

Enable intelligent prompt rewriting via LLM optimization.

false (default): Returns the image and original prompt. No extra cost.
true: Returns the image, an optimized prompt, and reasoning. Increases response time and cost — see model pricing for details.

integer

Random seed for reproducibility. Valid range: [0, 2147483647]. Using the same seed yields similar outputs. If omitted, a random seed is used.

Note: Image generation is probabilistic — even with the same seed, results may vary.

Required range:0 <= x <= 2147483647

Response

200-application/json

object

Model output.

Show child attributes

object[]

Model output content. Array contains one element.

Show child attributes

string

Reason for completion. stop indicates success.

Example:stop

object

Model response message.

Show child attributes

enum<string>

Message role. Always assistant.

Available options:assistant

object[]

Response content items. Contains an image object with the generated image URL and a text object with the prompt.

Show child attributes

string

Generated image URL (PNG). Valid for 24 hours — download promptly.

string

The original prompt (when prompt_extend=false) or the rewritten prompt (when prompt_extend=true).

string

Model reasoning output. Only returned when prompt_extend=true; empty string otherwise.

object

Usage statistics. Includes data for successful generations only.

Show child attributes

integer

Generated image width in pixels.

integer

Generated image height in pixels.

integer

Number of generated images. Always 1.

integer

Input tokens consumed. 0 when prompt_extend=false.

integer

Output tokens consumed. 0 when prompt_extend=false.

object

Output token breakdown. Only returned when prompt_extend=true.

Show child attributes

integer

Tokens used for reasoning.

integer

Total tokens consumed. 0 when prompt_extend=false.

string

Unique request identifier. Use for tracing and troubleshooting.

Example:abf1645b-b630-433a-92f6-xxxxxx