269 lines
9.0 KiB
Markdown
269 lines
9.0 KiB
Markdown
# 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>
|
||
|
||
## 效果示例
|
||
|
||
### 输入提示词
|
||
|
||
```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-turbo` | 轻量模型，快速生图 | 图像格式：PNG；单次固定返回 1 张；总像素范围：`[512*512, 2048*2048]` |
|
||
|
||
## 前提条件
|
||
|
||
1. 获取 API Key：<https://help.aliyun.com/zh/model-studio/get-api-key>
|
||
2. 配置环境变量：<https://help.aliyun.com/zh/model-studio/configure-api-key-through-environment-variables>
|
||
|
||
示例：
|
||
|
||
```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
|
||
```
|
||
|
||
## 计费与限流
|
||
|
||
- 模型价格与免费额度：<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>
|