Skip to main content

Z-Image API reference

A lightweight text-to-image model for fast generation, with Chinese and English text rendering, and flexible resolutions.

Try it online: (Beijing | Singapore) | Technical blog

Examples

Input prompt

Output image

film grain, analog film texture, soft film lighting, Kodak Portra 400 style, cinematic grainy texture, photorealistic details, subtle noise, (film grain:1.2). A close-up shot of a young East Asian woman in an outdoor snow scene. She has a slender build and is standing with her body slightly tilted to the right, head raised to look upwards, in a natural and relaxed pose. Her face has typical East Asian features, with fair skin and a natural blush on her cheeks. Her features are delicate: her eyes are dark brown and round, looking up with a slightly surprised expression, with the whites of her eyes visible; her eyebrows are dark black, naturally long and curved; her nose is small and straight, and her lips are painted with red lipstick, slightly parted, with an expression of mild surprise or curiosity. She has long, straight, dark black hair, slightly tousled by the wind, with some strands falling on the sides of her face. She is wearing a dark gray helmet on her head, with a few strands of hair showing at the edge. Her clothing is a heavy blue and white spliced jacket, which appears to be a combination of fleece and fabric, looking warm and thick, suitable for a snowy environment. The background is an outdoor scene covered in white snow, with blurry describes of trees in the distance. The sky is a bright light blue with a few white clouds. The lighting is strong natural daylight, illuminating her face and hair, creating clear light and shadow. The color palette is dominated by blue, white, and black, with an overall fresh and natural style. At the top of the frame is a black notification box with the white text "Press esc to exit full screen". The close-up perspective of the lens magnifies the character's expression and details, creating a realistic atmosphere of an outdoor snow scene.

image

Model overview

Model Name

Description

Output image specifications

z-image-turbo

A fast lightweight image generation model

Image resolution: 512×512 to 2048×2048 pixels. See recommended resolutions in size parameter settings.

Image format: png

Number of images: Fixed at 1.

Check Model List for region support before calling.

Prerequisites

Create an API key and set the API key as an environment variable.
Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
  • China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

Synchronous HTTP call

Beijing:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation Singapore:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation Replace {WorkspaceId} with your actual workspace ID.

Request parameters

Request headers
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
Request body
model string (Required)Model name: z-image-turbo.input object (Required)Input content.

Properties

messages array (Required)Request content array. Single-turn only — pass one role and content set. Multi-turn not supported.

Properties

rolestring (Required)Message role: user.contentarray (Required)Message content array. Must contain one text object.

Properties

textstring(Required)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 truncated.Example: A sitting orange cat with a happy expression, lively and cute, realistic and accurate.Note: Only one text object supported. Passing zero or multiple text objects returns an error.
parameters object (Optional)Image generation parameters.

Properties

size string (Optional)Output image resolution in width×height format.
  • Default: 1024*1536
  • Range: 512×512 to 2048×2048
  • Recommended: 1024×1024 to 1536×1536
Example: 1024*1536.

Recommended resolutions for a total of 1024*1024 pixels:

Recommended resolutions for a total of 1280*1280 pixels:

Recommended resolutions for a total of 1536*1536 pixels:

prompt_extend bool (Optional)
Enabling prompt_extend increases cost. See Model pricing for details.
Enable intelligent prompt rewriting via LLM optimization and reasoning output.
  • false (default): Returns image and original prompt
  • true: Returns image, optimized prompt, and reasoning
seed integer (optional)Random number seed. Valid range: [0,2147483647].Using the same seed yields similar outputs. If omitted, the algorithm uses a random seed.Note: Image generation is probabilistic. Even with the same seed, results may vary.
  • Text-to-image
This example returns an image directly for a faster response. To enable intelligent rewriting, set prompt_extend=true — the system returns the optimized prompt, reasoning, and image (increases response time).
curl --location 'https://{WorkspaceId}.cn-beijing.maas.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": "film grain, analog film texture, soft film lighting, Kodak Portra 400 style, cinematic grainy texture, photorealistic details, subtle noise, (film grain:1.2). A close-up shot of a young East Asian woman in an outdoor snow scene. She has a slender build and is standing with her body slightly tilted to the right, head raised to look upwards, in a natural and relaxed pose. Her face has typical East Asian features, with fair skin and a natural blush on her cheeks. Her features are delicate: her eyes are dark brown and round, looking up with a slightly surprised expression, with the whites of her eyes visible; her eyebrows are dark black, naturally long and curved; her nose is small and straight, and her lips are painted with red lipstick, slightly parted, with an expression of mild surprise or curiosity. She has long, straight, dark black hair, slightly tousled by the wind, with some strands falling on the sides of her face. She is wearing a dark gray helmet on her head, with a few strands of hair showing at the edge. Her clothing is a heavy blue and white spliced jacket, which appears to be a combination of fleece and fabric, looking warm and thick, suitable for a snowy environment. The background is an outdoor scene covered in white snow, with blurry describes of trees in the distance. The sky is a bright light blue with a few white clouds. The lighting is strong natural daylight, illuminating her face and hair, creating clear light and shadow. The color palette is dominated by blue, white, and black, with an overall fresh and natural style. At the top of the frame is a black notification box with the white text \"Press esc to exit full screen\". The close-up perspective of the lens magnifies the character's expression and details, creating a realistic atmosphere of an outdoor snow scene."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": false,
        "size": "1120*1440"
    }
}'

Response parameters

output objectModel output.

Properties

choices arrayModel output content. Array contains one element.

Properties

finish_reason stringReason for completion. Value stop indicates success.message objectModel response message.

Properties

rolestringMessage role. Value is assistant.contentarray

Properties

image stringGenerated image URL (PNG). Valid 24 hours — download promptly.text stringThis returns the input prompt (prompt_extend=false) or the rewritten prompt (prompt_extend=true).
reasoning_content stringModel reasoning process. Only returned when prompt_extend=true.
usage objectThis includes usage statistics for successful generations only.

Properties

width integerGenerated image width (pixels).height integerGenerated image height (pixels).image_count integerNumber of generated images: 1.input_tokens integerInput tokens (0 when prompt_extend=false).output_tokens integerOutput tokens (0 when prompt_extend=false).output_tokens_detailsobjectOutput token details (only when prompt_extend=true).

Properties

reasoning_tokensintegerTokens used for reasoning.
total_tokensintegerTotal tokens (0 when prompt_extend=false).
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Successful task execution
  • Abnormal task execution
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.
{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx"
                        },
                        {
                            "text": "film grain, analog film texture, soft film lighting, Kodak Portra 400 style, cinematic grainy texture, photorealistic details, subtle noise, (film grain:1.2). A close-up shot of a young East Asian woman in an outdoor snow scene. She has a slender build and is standing with her body slightly tilted to the right, head raised to look upwards, in a natural and relaxed pose. Her face has typical East Asian features, with fair skin and a natural blush on her cheeks. Her features are delicate: her eyes are dark brown and round, looking up with a slightly surprised expression, with the whites of her eyes visible; her eyebrows are dark black, naturally long and curved; her nose is small and straight, and her lips are painted with red lipstick, slightly parted, with an expression of mild surprise or curiosity. She has long, straight, dark black hair, slightly tousled by the wind, with some strands falling on the sides of her face. She is wearing a dark gray helmet on her head, with a few strands of hair showing at the edge. Her clothing is a heavy blue and white spliced jacket, which appears to be a combination of fleece and fabric, looking warm and thick, suitable for a snowy environment. The background is an outdoor scene covered in white snow, with blurry describes of trees in the distance. The sky is a bright light blue with a few white clouds. The lighting is strong natural daylight, illuminating her face and hair, creating clear light and shadow. The color palette is dominated by blue, white, and black, with an overall fresh and natural style. At the top of the frame is a black notification box with the white text \"Press esc to exit full screen\". The close-up perspective of the lens magnifies the character's expression and details, creating a realistic atmosphere of an outdoor snow scene."
                        }
                    ],
                    "reasoning_content": "",
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "height": 1440,
        "image_count": 1,
        "input_tokens": 0,
        "output_tokens": 0,
        "total_tokens": 0,
        "width": 1120
    },
    "request_id": "8a0809b4-a796-47f4-a095-394b02b62xxx"
}

Limits

  • Image URLs are valid for 24 hours. Download promptly.
  • Content moderation: Both the input prompt and output image undergo content moderation. Non-compliant content returns an IPInfringementSuspect or DataInspectionFailed error. See Error codes.

Billing and rate limiting

  • For pricing and free quota, see Model pricing.
  • For rate limits, see Z-Image.
  • Billing is based on successful image count and prompt_extend status. Failed calls do not incur fees or consume free quota.

Error codes

See Error codes for troubleshooting failed calls.

FAQ

Q: How do I view model invocation metrics?

A: One hour after a model invocation completes, go to the Monitoring (China (Beijing)) or Monitoring (Singapore) page to view metrics such as invocation count and success rate. For more information, see Billing and cost management.

Q: How do I get the domain name whitelist for image storage?

A: Images generated by models are stored in OSS. The API returns a temporary public URL. To configure a firewall whitelist for this download URL, note the following: The underlying storage may change dynamically. This topic does not provide a fixed OSS domain name whitelist to prevent access issues caused by outdated information. If you have security control requirements, contact your account manager to obtain the latest OSS domain name list.
Text Generation
Image Generation
Video Generation
World models
3D Model Generation
Audio
  • Audio generation
Realtime API
Text Embedding
Decision Model
TokenPlan
Model Production