Files

admin 8df2095acf chore(repo): keep only current main snapshot

History squashed to one root commit to permanently drop old branch history and objects.

2026-02-28 16:41:12 +08:00

9.0 KiB

Raw Blame History

Z-Image 文生图 API 指南

Z-Image 是一款轻量级文生图模型，支持快速出图、中英文文本渲染，以及多种分辨率和宽高比。

快速入口

在线体验（北京）：https://bailian.console.aliyun.com/cn-beijing/?tab=model#/efm/model_experience_center/vision?currentTab=imageGenerate&modelId=z-image-turbo
在线体验（新加坡）：https://modelstudio.console.aliyun.com/ap-southeast-1?tab=dashboard#/efm/model_experience_center/vision?currentTab=imageGenerate&modelId=z-image-turbo
技术博客：https://tongyi-mai.github.io/Z-Image-blog/
模型列表（按地域）：https://help.aliyun.com/zh/model-studio/models#b77c038c56b7y

效果示例

输入提示词

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-turbo`	轻量模型，快速生图	图像格式：PNG；单次固定返回 1 张；总像素范围：`[512512, 20482048]`

前提条件

获取 API Key：https://help.aliyun.com/zh/model-studio/get-api-key
配置环境变量：https://help.aliyun.com/zh/model-studio/configure-api-key-through-environment-variables

示例：

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 时会返回优化后的提示词和推理过程，但耗时与费用更高。

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	否	输出分辨率，格式 `宽高`，默认 `10241536`
`parameters.prompt_extend`	bool	否	是否启用提示词智能改写，默认 `false`
`parameters.seed`	integer	否	随机种子，范围 `[0, 2147483647]`

size 参数说明

总像素限制：[512*512, 2048*2048]
推荐总像素范围：[1024*1024, 1536*1536]
同一 seed 可提升结果稳定性，但不能保证完全一致

宽高比	分辨率
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`

宽高比	分辨率
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`

宽高比	分辨率
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 小时，请及时保存。

{
  "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"
}

失败响应

{
  "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，请将下列域名加入白名单：

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

计费与限流

模型价格与免费额度：https://help.aliyun.com/zh/model-studio/model-pricing#6713612f55h4l
限流说明：https://help.aliyun.com/zh/model-studio/rate-limit#e17ad85fd8wwl
计费按成功生成的图像张数统计；失败请求不计费，也不消耗免费额度：https://help.aliyun.com/zh/model-studio/new-free-quota

错误码

错误码总览：https://help.aliyun.com/zh/model-studio/error-code

常见问题

如何查看模型调用量？

模型调用约 1 小时后，可在以下页面查看调用次数、成功率等指标：

模型监控（北京）：https://bailian.console.aliyun.com/cn-beijing/?tab=model#/model-telemetry
模型监控（新加坡）：https://modelstudio.console.aliyuncs.com/ap-southeast-1?tab=dashboard#/model-telemetry
账单查询与成本管理：https://help.aliyun.com/zh/model-studio/bill-query-and-cost-management

9.0 KiB

Raw Blame History

Z-Image 文生图 API 指南

快速入口

效果示例

输入提示词

输出图像

模型概览

前提条件

HTTP 同步调用

请求示例

请求参数

Headers

Body

size 参数说明

推荐分辨率

总像素约 1024x1024

总像素约 1280x1280

总像素约 1536x1536

响应示例

成功响应

失败响应

响应字段说明

使用限制

计费与限流

错误码

常见问题

如何查看模型调用量？

9.0 KiB Raw Blame History Unescape Escape

Z-Image 文生图 API 指南

快速入口

效果示例

输入提示词

输出图像

模型概览

前提条件

HTTP 同步调用

请求示例

请求参数

Headers

Body

size 参数说明

推荐分辨率

总像素约 1024x1024

总像素约 1280x1280

总像素约 1536x1536

响应示例

成功响应

失败响应

响应字段说明

使用限制

计费与限流

错误码

常见问题

如何查看模型调用量？

9.0 KiB

Raw Blame History