Skip to main content
Z-Image

Z-Image API参考

Z-Image 是一款轻量级文生图模型,可快速生成图像,支持中英文字渲染,并灵活适配多种分辨率与宽高比例。

快速入口:在线体验(北京 | 新加坡) | 技术博客

效果展示

输入提示词

输出图像

film grain, analog film texture, soft film lighting, Kodak Portra 400 style, cinematic grainy texture, photorealistic details, subtle noise, (film grain:1.2)。采用近景特写镜头拍摄的东亚年轻女性,呈现户外雪地场景。她体型纤瘦,呈站立姿势,身体微微向右侧倾斜,头部抬起看向画面上方,姿态自然放松。她的面部是典型东亚长相,肤色白皙,脸颊带有自然的红润感,五官清秀:眼睛是深棕色,眼型偏圆,眼神略带惊讶地望向上方,眼白部分可见;眉毛是深黑色,形状自然弯长;鼻子小巧挺直,嘴唇涂有红色口红,唇瓣微张,表情带着轻微的惊讶或好奇。她的头发是深黑色长直发,发丝被风吹得略显凌乱,部分垂在脸颊两侧,头顶佩戴一顶深灰色的头盔,头盔边缘露出少量发丝。服装是蓝白拼接的厚重外套,外套材质看起来是毛绒与布料结合,显得温暖厚实,适合雪地环境。背景是被白雪覆盖的户外场景,远处可见模糊的树木轮廓,天空是明亮的浅蓝色,带有少量白云,光线是强烈的自然日光,照亮人物面部与头发,形成清晰的光影,色调以蓝、白、黑为主,整体风格清新自然。画面顶部有黑色提示框,内有“Press esc to exit full screen”的白色文字。镜头的近景视角放大了人物的表情与细节,营造出户外雪地的真实氛围。

image

模型概览

模型名称

模型简介

输出图像规格

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}.cn-beijing.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/jsonAuthorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。
请求体(Request Body)
model string (必选)模型名称。必须为:z-image-turbo。input object (必选)输入的基本信息。

属性

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

属性

rolestring (必选)消息的角色。此参数必须设置为usercontentarray (必选)消息内容数组。必须包含且仅包含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}.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)。采用近景特写镜头拍摄的东亚年轻女性,呈现户外雪地场景。她体型纤瘦,呈站立姿势,身体微微向右侧倾斜,头部抬起看向画面上方,姿态自然放松。她的面部是典型东亚长相,肤色白皙,脸颊带有自然的红润感,五官清秀:眼睛是深棕色,眼型偏圆,眼神略带惊讶地望向上方,眼白部分可见;眉毛是深黑色,形状自然弯长;鼻子小巧挺直,嘴唇涂有红色口红,唇瓣微张,表情带着轻微的惊讶或好奇。她的头发是深黑色长直发,发丝被风吹得略显凌乱,部分垂在脸颊两侧,头顶佩戴一顶深灰色的头盔,头盔边缘露出少量发丝。服装是蓝白拼接的厚重外套,外套材质看起来是毛绒与布料结合,显得温暖厚实,适合雪地环境。背景是被白雪覆盖的户外场景,远处可见模糊的树木轮廓,天空是明亮的浅蓝色,带有少量白云,光线是强烈的自然日光,照亮人物面部与头发,形成清晰的光影,色调以蓝、白、黑为主,整体风格清新自然。画面顶部有黑色提示框,内有“Press esc to exit full screen”的白色文字。镜头的近景视角放大了人物的表情与细节,营造出户外雪地的真实氛围。"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": false,
        "size": "1120*1440"
    }
}'

响应参数

output object任务输出信息。

属性

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

属性

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

属性

rolestring消息的角色,固定为assistantcontentarray

属性

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": "film grain, analog film texture, soft film lighting, Kodak Portra 400 style, cinematic grainy texture, photorealistic details, subtle noise, (film grain:1.2)。采用近景特写镜头拍摄的东亚年轻女性,呈现户外雪地场景。她体型纤瘦,呈站立姿势,身体微微向右侧倾斜,头部抬起看向画面上方,姿态自然放松。她的面部是典型东亚长相,肤色白皙,脸颊带有自然的红润感,五官清秀:眼睛是深棕色,眼型偏圆,眼神略带惊讶地望向上方,眼白部分可见;眉毛是深黑色,形状自然弯长;鼻子小巧挺直,嘴唇涂有红色口红,唇瓣微张,表情带着轻微的惊讶或好奇。她的头发是深黑色长直发,发丝被风吹得略显凌乱,部分垂在脸颊两侧,头顶佩戴一顶深灰色的头盔,头盔边缘露出少量发丝。服装是蓝白拼接的厚重外套,外套材质看起来是毛绒与布料结合,显得温暖厚实,适合雪地环境。背景是被白雪覆盖的户外场景,远处可见模糊的树木轮廓,天空是明亮的浅蓝色,带有少量白云,光线是强烈的自然日光,照亮人物面部与头发,形成清晰的光影,色调以蓝、白、黑为主,整体风格清新自然。画面顶部有黑色提示框,内有“Press esc to exit full screen”的白色文字。镜头的近景视角放大了人物的表情与细节,营造出户外雪地的真实氛围。"
                        }
                    ],
                    "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"
}

使用限制

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

计费与限流

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

错误码

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

常见问题

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

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

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

A: 模型生成的图像存储于阿里云OSS,API将返回一个临时的公网URL(链接有效期为 24 小时,请及时下载保存)。图片URL的域名格式为dashscope-{标识}.oss-accelerate.aliyuncs.comdashscope-{标识}.oss-cn-{地域}.aliyuncs.com若需要对该下载地址进行防火墙白名单配置,请注意:由于底层存储会动态变更,以下bucket名称仅供参考,可能随时更新:dashscope-a717、dashscope-66f3、dashscope-7c2c、dashscope-2522、dashscope-c72b、dashscope-0484、dashscope-7e0f、dashscope-5859、dashscope-5496、dashscope-35f9、dashscope-31d9、dashscope-7f1f、dashscope-cc75、dashscope-64e9。为避免过期信息影响访问,文档不提供固定的OSS域名白名单。如有安全管控需求,请联系客户经理获取最新OSS域名列表。API当前仅支持返回URL格式,不支持base64格式输出。