A lightweight text-to-image model for fast generation, with Chinese and English text rendering, and flexible resolutions.
Examples
Input prompt | Output image |
|---|---|
Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist. The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.” Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement. Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing. | ![]() |
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
Singapore:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Beijing: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.
