Skip to main content
Z-Image

Z-Image API参考

Z-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.

b16c8008-83c1-4c80-ae22-786a2299bec3-1-转换自-png

模型概览

模型名称

模型简介

输出图像规格

z-image-turbo

轻量模型，快速生图

图像分辨率：总像素在[512*512, 2048*2048]之间，推荐分辨率请参见size参数设置

图像格式：png

图像张数：固定1张

调用前，请查阅各地域支持的模型列表。

前提条件

您需要获取与配置 API Key，并配置API Key到环境变量。
阿里云百炼为华北2（北京）、新加坡地域推出了业务空间专属域名，能够为推理请求提供卓越的性能和更高的稳定性，建议迁移至新域名：
  • 华北2（北京）地域：从 https://dashscope.aliyuncs.com 迁移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地域：从 https://dashscope-intl.aliyuncs.com 迁移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
其中 {WorkspaceId} 为您的业务空间 ID，可在阿里云百炼控制台的业务空间详情页面查看。现有域名仍可正常使用。

HTTP同步调用

新加坡地域：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation 北京地域：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation 调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求参数

请求头（Headers）
Content-Typestring（必选）请求内容类型。此参数必须设置为application/json。Authorizationstring（必选）请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值：Bearer sk-xxxx。
请求体（Request Body）
model string （必选）模型名称。必须为：z-image-turbo。input object （必选）输入的基本信息。

属性

messages array （必选）请求内容数组。当前仅支持单轮对话，即传入一组role、content参数，不支持多轮对话。

属性

rolestring （必选）消息的角色。此参数必须设置为user。contentarray （必选）消息内容数组。必须包含且仅包含1 个 text 对象。

属性

textstring（必选）正向提示词用于描述期望生成的图像内容、风格和构图。支持中英文，长度不超过800个字符，每个汉字、字母、数字或符号计为一个字符，超过部分会自动截断。示例值：一只坐着的橘黄色的猫，表情愉悦，活泼可爱，逼真准确。注意：仅支持传入一个text，不传或传入多个将报错。
parameters object （可选）图像处理参数。

属性

size string （可选）输出图像的分辨率，格式为宽*高。
  • 默认值：1024*1536。
  • 总像素范围限制：总像素在 [512512, 20482048]之间。
  • 推荐分辨率范围：总像素在 [10241024, 15361536]之间，出图效果更佳。
示例值：1024*1536。

总像素为1024*1024的推荐分辨率：

  • 1:1: 1024*1024
  • 2:3: 832*1248
  • 3:2: 1248*832
  • 3:4: 864*1152
  • 4:3: 1152*864
  • 7:9: 896*1152
  • 9:7: 1152*896
  • 9:16: 720*1280
  • 9:21: 576*1344
  • 16:9: 1280*720
  • 21:9：1344*576

总像素为1280*1280的推荐分辨率：

  • 1:1: 1280*1280
  • 2:3: 1024*1536
  • 3:2: 1536*1024
  • 3:4: 1104*1472
  • 4:3: 1472*1104
  • 7:9: 1120*1440
  • 9:7: 1440*1120
  • 9:16: 864*1536
  • 9:21: 720*1680
  • 16:9: 1536*864
  • 21:9: 1680*720

总像素为1536*1536的推荐分辨率：

  • 1:1：1536*1536
  • 2:3: 1248*1872
  • 3:2: 1872*1248
  • 3:4: 1296*1728
  • 4:3: 1728*1296
  • 7:9: 1344*1728
  • 9:7: 1728*1344
  • 9:16: 1152*2048
  • 9:21: 864*2016
  • 16:9: 2048*1152
  • 21:9: 2016*864
prompt_extend bool （可选）
prompt_extend直接影响费用。设为 true 时价格高于 false，具体见参见模型价格。
是否启用智能提示词（text）改写。开启后，将使用大模型优化提示词，并输出思考过程。
  • false：默认值，关闭智能改写。输出图像和原始文本提示词。
  • true：开启智能改写。输出图像、优化后的文本提示词、思考过程。
seed integer （可选）随机数种子，取值范围[0,2147483647]。使用相同的seed参数值可使生成内容保持相对稳定。若不提供，算法将自动使用随机数种子。注意：模型生成过程具有概率性，即使使用相同的seed，也不能保证每次生成结果完全一致。
  • 文生图
以下示例直接返回图片，响应速度较快。若想开启“智能思考”能力，请设置prompt_extend=true 。开启后，系统将在返回图片的同时，返回优化后的提示词及其推理过程，但会增加响应时间。
curl --location 'https://{WorkspaceId}.ap-southeast-1.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": "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."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": false,
        "size": "1024*1024"
    }
}'

响应参数

output object任务输出信息。

属性

choices array模型生成的输出内容。此数组仅包含1个元素。

属性

finish_reason string任务停止原因，正常完成时为 stop。message object模型返回的消息。

属性

rolestring消息的角色，固定为assistant。contentarray

属性

image string生成图像的 URL，图像格式为PNG。链接有效期为24小时，请及时下载并保存图像。text string
  • 当prompt_extend=false时，为输入的提示词。
  • 当prompt_extend=true时，为改写后的提示词。
reasoning_content string模型的思考过程，仅在prompt_extend=true时返回思考文本。
usage object输出信息统计。只对成功的结果计数。

属性

width integer生成图像的宽度（像素）。height integer生成图像的高度（像素）。image_count integer生成图像的数量，固定为1。input_tokens integer输入token数量，prompt_extend=false时固定为0。output_tokens integer输出token数量，prompt_extend=false时固定为0。output_tokens_detailsobject输出 token 详情，仅当prompt_extend=true时返回。

属性

reasoning_tokensinteger推理思考使用的 token 数量。
total_tokensinteger总token数量，prompt_extend=false时固定为0。
request_idstring请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数，详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误码。
  • 任务执行成功
  • 任务执行异常
任务数据（如任务状态、图像URL等）仅保留24小时，超时后会被自动清除。请您务必及时保存生成的图像。
{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx"
                        },
                        {
                            "text": "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."
                        }
                    ],
                    "reasoning_content": "",
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "height": 1024,
        "image_count": 1,
        "input_tokens": 0,
        "output_tokens": 0,
        "total_tokens": 0,
        "width": 1024
    },
    "request_id": "abf1645b-b630-433a-92f6-xxxxxx"
}

使用限制

  • 图像url均只保留 24 小时，请及时下载。
  • 内容审核：输入的 prompt 和输出的图像均会经过内容安全审核，包含违规内容的请求将报错“IPInfringementSuspect”或“DataInspectionFailed”，具体参见错误码。

计费与限流

  • 模型免费额度和计费单价请参见模型价格。
  • 模型限流请参见Z-Image。
  • 根据是否开启智能按成功生成的 图像张数 计费。模型调用失败或处理错误不产生任何费用，也不消耗免费额度。

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。

常见问题

Q: 如何查看模型调用量？

A: 模型调用完一小时后，请在 模型监控（新加坡）或模型监控（北京）页面，查看模型的调用次数、成功率等指标。详情请参见账单查询与成本管理。

Q：如何获取图像存储的访问域名白名单？

A： 模型生成的图像存储于阿里云OSS，API将返回一个临时的公网URL。若需要对该下载地址进行防火墙白名单配置，请注意：由于底层存储会根据业务情况进行动态变更，为避免过期信息影响访问，文档不提供固定的OSS域名白名单。如有安全管控需求，请联系客户经理获取最新OSS域名列表。
使用 API
文本生成
图像生成
视频生成
音频
实时多模态
Realtime API
  • 概述
向量与排序
更多模型
工具包/框架
模型生产
文件管理
账单
更多