BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Imagem Z
Geração rápida e leve
Obtenha uma chave de API e defini-lo como uma variável de ambiente. Se estiver usando o SDK, instale-o.
Z-Image é um modelo leve de texto para imagem que gera imagens rapidamente. Ele renderiza texto em chinês e inglês e se adapta a várias resoluções e proporções.
Links rápidos: Experimente on-line | Blog técnico
OpenAPI
openapi: 3.1.0
info:
title: Z-Image API
description: Z-Image text-to-image generation API.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com/api/v1
description: Singapore
security:
- BearerAuth: []
paths:
/services/aigc/multimodal-generation/generation:
post:
operationId: createZImage
summary: Generate image
description: Generate an image from a text prompt using z-image-turbo. Returns the result synchronously — no polling required.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ZImageRequest"
responses:
"200":
description: Image generation result
content:
application/json:
schema:
$ref: "#/components/schemas/ZImageResponse"
examples:
success:
summary: Successful generation
value:
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
"400":
description: Invalid request parameters
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
error:
summary: Parameter error
value:
request_id: a4d78a5f-655f-9639-8437-xxxxxx
code: InvalidParameter
message: num_images_per_prompt must be 1
"401":
description: Authentication failed — invalid or missing API key
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"429":
description: Rate limit exceeded
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --location 'https://maas.qwencloudapi.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"
}
}'
- lang: python
label: Python (DashScope SDK)
source: |-
import os
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
messages = [
{
"role": "user",
"content": [
{"text": "A sitting orange cat with a happy expression, lively and cute, realistic and accurate"}
]
}
]
rsp = MultiModalConversation.call(
api_key=api_key,
model='z-image-turbo',
messages=messages)
if rsp.status_code == HTTPStatus.OK:
content = rsp.output.choices[0].message.content
for item in content:
if 'image' in item:
print("Image URL:", item['image'])
file_name = PurePosixPath(
unquote(urlparse(item['image']).path)).name
with open(file_name, 'wb') as f:
f.write(requests.get(item['image']).content)
print("Saved to:", file_name)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
- lang: java
label: Java (DashScope SDK)
source: |-
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.*;
public class ZImageGen {
static {
Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
}
public static void main(String[] args) {
try {
MultiModalConversation conv = new MultiModalConversation();
Map<String, Object> textContent = new HashMap<>();
textContent.put("text", "A sitting orange cat with a happy expression, lively and cute, realistic and accurate");
MultiModalMessage userMsg = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Collections.singletonList(textContent))
.build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("z-image-turbo")
.messages(Collections.singletonList(userMsg))
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
} catch (Exception e) {
System.out.println(e.getMessage());
}
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: DashScope API key. Create one in the [QwenCloud console](https://home.qwencloud.com/api-keys). Alternatively, pass it via the `X-DashScope-ApiKey` request header.
schemas:
ZImageRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: Model name.
enum:
- z-image-turbo
example: z-image-turbo
input:
type: object
required:
- messages
description: Input content.
properties:
messages:
type: array
description: "Request content array. **Single-turn only** — pass one message with `role: user`. Multi-turn is not supported."
minItems: 1
maxItems: 1
items:
$ref: "#/components/schemas/ZImageMessage"
parameters:
$ref: "#/components/schemas/ZImageParameters"
ZImageMessage:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
description: Message role. Must be `user`.
content:
type: array
description: Message content array. Must contain exactly one text object. Passing zero or multiple text objects returns an error.
items:
$ref: "#/components/schemas/ZImageContentPart"
ZImageContentPart:
type: object
properties:
text:
type: string
description: 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.
maxLength: 800
example: A sitting orange cat with a happy expression, lively and cute, realistic and accurate
ZImageParameters:
type: object
description: Image generation parameters.
properties:
size:
type: string
description: |-
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).
default: 1024*1536
example: 1024*1024
prompt_extend:
type: boolean
description: |-
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.
default: false
seed:
type: integer
description: |-
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.
minimum: 0
maximum: 2147483647
ZImageResponse:
type: object
description: Image generation response.
properties:
output:
type: object
description: Model output.
properties:
choices:
type: array
description: Model output content. Array contains one element.
items:
$ref: "#/components/schemas/ZImageChoice"
usage:
$ref: "#/components/schemas/ZImageUsage"
request_id:
type: string
description: Unique request identifier. Use for tracing and troubleshooting.
example: abf1645b-b630-433a-92f6-xxxxxx
ZImageChoice:
type: object
properties:
finish_reason:
type: string
description: Reason for completion. `stop` indicates success.
example: stop
message:
type: object
description: Model response message.
properties:
role:
type: string
description: Message role. Always `assistant`.
enum:
- assistant
content:
type: array
description: Response content items. Contains an `image` object with the generated image URL and a `text` object with the prompt.
items:
$ref: "#/components/schemas/ZImageResponseContentPart"
reasoning_content:
type: string
description: Model reasoning output. Only returned when `prompt_extend=true`; empty string otherwise.
ZImageResponseContentPart:
type: object
description: A content item in the response. Each item contains either an `image` or a `text` field.
properties:
image:
type: string
description: Generated image URL (PNG). **Valid for 24 hours** — download promptly.
text:
type: string
description: The original prompt (when `prompt_extend=false`) or the rewritten prompt (when `prompt_extend=true`).
ZImageUsage:
type: object
description: Usage statistics. Includes data for successful generations only.
properties:
width:
type: integer
description: Generated image width in pixels.
height:
type: integer
description: Generated image height in pixels.
image_count:
type: integer
description: Number of generated images. Always 1.
input_tokens:
type: integer
description: Input tokens consumed. `0` when `prompt_extend=false`.
output_tokens:
type: integer
description: Output tokens consumed. `0` when `prompt_extend=false`.
output_tokens_details:
type: object
description: Output token breakdown. Only returned when `prompt_extend=true`.
properties:
reasoning_tokens:
type: integer
description: Tokens used for reasoning.
total_tokens:
type: integer
description: Total tokens consumed. `0` when `prompt_extend=false`.
ErrorResponse:
type: object
description: Error response. Returned when the request fails.
properties:
request_id:
type: string
description: Unique request identifier.
code:
type: string
description: Error code (e.g., `InvalidParameter`, `Throttling`, `Unauthorized`).
example: InvalidParameter
message:
type: string
description: Human-readable error message.
example: num_images_per_prompt must be 1