全部产品
Search
文档中心

大模型服务平台百炼:通义-文生图-Z-Image API参考

更新时间:Dec 25, 2025

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

快速入口技术博客

前提条件

您需要获取与配置 API Key,并配置API Key到环境变量

效果展示

输入提示词

输出图像

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张

说明

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

HTTP同步调用

新加坡地域POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

北京地域POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

请求参数

文生图

以下示例直接返回图片,响应速度较快。

若想开启“智能思考”能力,请设置prompt_extend=true 。开启后,系统将在返回图片的同时,返回优化后的提示词及其推理过程,但会增加响应时间。

以下为国际(新加坡)地域base_url,若使用中国大陆(北京)地域的模型,需将base_url替换为https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
curl --location 'https://dashscope-intl.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"
    }
}'

请求头(Headers)

Content-Type string (必选)

请求内容类型。此参数必须设置为application/json

Authorization string(必选)

请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值:Bearer sk-xxxx。

请求体(Request Body)

model string (必选)

模型名称。

示例值:z-image-turbo。

input object (必选)

输入的基本信息。

属性

messages array (必选)

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

属性

role string (必选)

消息的角色。此参数必须设置为user

content array (必选)

消息内容数组。必须包含且仅包含 1 个 text 对象

属性

text string (必选)

正向提示词用于描述期望生成的图像内容、风格和构图。

支持中英文,长度不超过800个字符,每个汉字、字母、数字或符号计为一个字符,超过部分会自动截断。

示例值:一只坐着的橘黄色的猫,表情愉悦,活泼可爱,逼真准确。

注意:仅支持传入一个text,不传或传入多个将报错。

parameters object (可选)

图像处理参数。

属性

size string (可选)

输出图像的分辨率,格式为宽*高。默认值和约束因模型版本而异:

  • 默认值:1024*1536

  • 总像素范围限制:总像素在 [512*512, 2048*2048]之间。

  • 推荐分辨率范围:总像素在 [1024*1024, 1536*1536]之间,出图效果更佳。

示例值: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,也不能保证每次生成结果完全一致。

响应参数

任务执行成功

任务数据(如任务状态、图像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"
}

任务执行异常

如果因为某种原因导致任务执行失败,将返回相关信息,可以通过code和message字段明确指示错误原因。请参见错误信息进行解决。

{
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

output object

任务输出信息。

属性

choices array

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

属性

finish_reason string

任务停止原因,正常完成时为 stop

messages object

模型返回的消息。

属性

role string

消息的角色,固定为assistant

content array

属性

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数量。

output_tokens integer

输出token数量。

output_tokens_details object

输出 token 详情。

output_tokens_details.reasoning_tokens integer

推理思考使用的 token 数量。

total_tokens integer

总token数量。

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

code string

请求失败的错误码。请求成功时不会返回此参数,详情请参见错误信息

message string

请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误信息

使用限制

  • 数据时效:任务task_id和 图像url均只保留 24 小时,过期后将无法查询或下载。

  • 内容审核:输入的 prompt 和输出的图像均会经过内容安全审核,包含违规内容的请求将报错“IPInfringementSuspect”或“DataInspectionFailed”,具体参见错误信息

  • 网络访问配置:图像链接存储于阿里云 OSS,如果业务系统因安全策略无法访问外部OSS链接,请将以下 OSS 域名加入网络访问白名单。

    # OSS域名列表
    dashscope-result-bj.oss-cn-beijing.aliyuncs.com
    dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
    dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
    dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
    dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
    dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
    dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
    dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
    dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
    dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

计费与限流

  • 模型免费额度和计费单价请参见模型价格

  • 模型限流请参见通义-文生图-Z-Image

  • 计费说明:

    • 根据是否开启智能按成功生成的 图像张数 计费。仅当查询结果接口返回task_statusSUCCEEDED 并成功生成图像后,才会计费。

    • 模型调用失败或处理错误不产生任何费用,也不消耗免费额度

错误码

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

常见问题

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

A: 模型调用完一小时后,请在模型观测(新加坡)模型观测(北京)页面,查看模型的调用次数、成功率等指标。如何查看模型调用记录?