A lightweight text-to-image model for fast generation, with Chinese and English text rendering, and flexible resolutions.
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. | ![]() |
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. |
Prerequisites
Create an API key and set the API key as an environment variable.
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 parametersRequest headersContent-Typestring (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 bodymodelstring (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 role string (Required)Message role: user.contentarray (Required)Message content array. Must contain one text object.
Properties text string(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.object (Optional)Image generation parameters.
Properties size string (Optional)Output image resolution in width×height format.
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:
bool (Optional)Enable intelligent prompt rewriting via LLM optimization and reasoning output.
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. |
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). |
Response parametersoutputobjectModel 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 role stringMessage 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).stringModel reasoning process. Only returned when prompt_extend=true.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_tokens integerTokens used for reasoning.integerTotal tokens (0 when prompt_extend=false).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. |
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. |
Limits
- Image URLs are valid for 24 hours. Download promptly.
- Content moderation: Both the input
promptand output image undergo content moderation. Non-compliant content returns anIPInfringementSuspectorDataInspectionFailederror. 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.
