# Z-Image 文生图 API 指南 Z-Image 是一款轻量级文生图模型，支持快速出图、中英文文本渲染，以及多种分辨率和宽高比。 ## 快速入口 - 在线体验（北京）： - 在线体验（新加坡）： - 技术博客： - 模型列表（按地域）： ## 效果示例 ### 输入提示词 ```text film grain, analog film texture, soft film lighting, Kodak Portra 400 style, cinematic grainy texture, photorealistic details, subtle noise, (film grain:1.2)。 采用近景特写镜头拍摄的东亚年轻女性，站在户外雪地中，神情带有轻微惊讶。 整体画面清新自然，主色调为蓝、白、黑。 ``` ### 输出图像 ![Z-Image 输出示例](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6915736671/p1036890.png) ## 模型概览 | 模型名称 | 模型简介 | 输出规格 | | --- | --- | --- | | `z-image-turbo` | 轻量模型，快速生图 | 图像格式：PNG；单次固定返回 1 张；总像素范围：`[512*512, 2048*2048]` | ## 前提条件 1. 获取 API Key： 2. 配置环境变量： 示例： ```bash export DASHSCOPE_API_KEY="sk-xxxxxxxx" ``` ## HTTP 同步调用 - 北京地域：`POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` - 新加坡地域：`POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` ### 请求示例 `prompt_extend=false` 时响应更快，仅返回图像与提示词； `prompt_extend=true` 时会返回优化后的提示词和推理过程，但耗时与费用更高。 ```bash curl --location 'https://dashscope.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": "一只坐在窗边的橘猫，午后阳光，胶片质感，写实风格。" } ] } ] }, "parameters": { "prompt_extend": false, "size": "1120*1440" } }' ``` ## 请求参数 ### Headers | 参数 | 类型 | 必选 | 说明 | | --- | --- | --- | --- | | `Content-Type` | string | 是 | 固定为 `application/json` | | `Authorization` | string | 是 | 鉴权信息，格式：`Bearer $DASHSCOPE_API_KEY` | ### Body | 参数路径 | 类型 | 必选 | 说明 | | --- | --- | --- | --- | | `model` | string | 是 | 模型名称，固定为 `z-image-turbo` | | `input` | object | 是 | 输入对象 | | `input.messages` | array | 是 | 消息数组，仅支持单轮输入 | | `input.messages[0].role` | string | 是 | 固定为 `user` | | `input.messages[0].content` | array | 是 | 内容数组，必须且仅能包含 1 个 `text` 对象 | | `input.messages[0].content[0].text` | string | 是 | 正向提示词（中英文均可），长度上限 800 字符，超长自动截断 | | `parameters` | object | 否 | 生成参数对象 | | `parameters.size` | string | 否 | 输出分辨率，格式 `宽*高`，默认 `1024*1536` | | `parameters.prompt_extend` | bool | 否 | 是否启用提示词智能改写，默认 `false` | | `parameters.seed` | integer | 否 | 随机种子，范围 `[0, 2147483647]` | ### size 参数说明 - 总像素限制：`[512*512, 2048*2048]` - 推荐总像素范围：`[1024*1024, 1536*1536]` - 同一 `seed` 可提升结果稳定性，但不能保证完全一致 ### 推荐分辨率 #### 总像素约 1024x1024 | 宽高比 | 分辨率 | | --- | --- | | 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` | #### 总像素约 1280x1280 | 宽高比 | 分辨率 | | --- | --- | | 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` | #### 总像素约 1536x1536 | 宽高比 | 分辨率 | | --- | --- | | 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` | ## 响应示例 ### 成功响应 任务数据（如图像 URL）仅保留 24 小时，请及时保存。 ```json { "output": { "choices": [ { "finish_reason": "stop", "message": { "role": "assistant", "content": [ { "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx" }, { "text": "一只坐在窗边的橘猫，午后阳光，胶片质感，写实风格。" } ], "reasoning_content": "" } } ] }, "usage": { "width": 1120, "height": 1440, "image_count": 1, "input_tokens": 0, "output_tokens": 0, "total_tokens": 0 }, "request_id": "8a0809b4-a796-47f4-a095-394b02b62xxx" } ``` ### 失败响应 ```json { "request_id": "a4d78a5f-655f-9639-8437-xxxxxx", "code": "InvalidParameter", "message": "num_images_per_prompt must be 1" } ``` ## 响应字段说明 | 参数路径 | 类型 | 说明 | | --- | --- | --- | | `output` | object | 任务输出信息 | | `output.choices` | array | 模型输出数组，仅包含 1 个元素 | | `output.choices[0].finish_reason` | string | 停止原因，正常完成为 `stop` | | `output.choices[0].message.role` | string | 固定为 `assistant` | | `output.choices[0].message.content[].image` | string | 生成图像 URL（PNG，24 小时有效） | | `output.choices[0].message.content[].text` | string | `prompt_extend=false` 返回原提示词；`true` 返回改写后提示词 | | `output.choices[0].message.reasoning_content` | string | 推理过程，仅 `prompt_extend=true` 时返回 | | `usage` | object | 统计信息 | | `usage.width` | integer | 图像宽度（像素） | | `usage.height` | integer | 图像高度（像素） | | `usage.image_count` | integer | 图像数量，固定为 1 | | `usage.input_tokens` | integer | 输入 token 数，`prompt_extend=false` 时固定为 0 | | `usage.output_tokens` | integer | 输出 token 数，`prompt_extend=false` 时固定为 0 | | `usage.output_tokens_details.reasoning_tokens` | integer | 推理 token 数，仅 `prompt_extend=true` 时返回 | | `usage.total_tokens` | integer | 总 token 数，`prompt_extend=false` 时固定为 0 | | `request_id` | string | 请求唯一标识，可用于排障 | | `code` | string | 错误码，仅失败时返回 | | `message` | string | 错误详情，仅失败时返回 | ## 使用限制 - 图像 URL 仅保留 24 小时，请及时下载。 - 输入 `prompt` 与输出图像均经过内容安全审核，违规请求可能返回 `IPInfringementSuspect` 或 `DataInspectionFailed`。 - 若业务网络禁止访问公网 OSS，请将下列域名加入白名单： ```text 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 ``` ## 计费与限流 - 模型价格与免费额度： - 限流说明： - 计费按成功生成的图像张数统计；失败请求不计费，也不消耗免费额度： ## 错误码 错误码总览： ## 常见问题 ### 如何查看模型调用量？ 模型调用约 1 小时后，可在以下页面查看调用次数、成功率等指标： - 模型监控（北京）： - 模型监控（新加坡）： - 账单查询与成本管理：