@henjicc/ai-sdk 0.9.0 → 0.10.0

package/docs/model-adaptation/Z-Image-Turbo/Z-Image-Turbo_Fal.md

@@ -1,95 +1,103 @@
-# Z-Image Turbo · Fal
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-28 |
-| 模态 | 图片 |
-| 供应商 | fal.ai（聚合平台） |
-| 平台模型 ID | `fal-ai/z-image/turbo`、`fal-ai/z-image/turbo/image-to-image` |
-| 接口形态 | 队列异步（推荐）或同步直连 |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-> **Fal 是唯一提供 Z-Image 图生图能力的供应商**（百炼官方、APIMart、KIE 都只有文生图）。
-
-## 1. 接入协议（Fal 通用）
-
-- **鉴权**：`Authorization: Key $FAL_KEY`
-- **同步**：`POST https://fal.run/<endpoint-id>`
-- **队列**：`POST https://queue.fal.run/<endpoint-id>` → `{ request_id, status_url, response_url, cancel_url }`；`GET .../requests/{id}/status`（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`）；`GET .../requests/{id}` 取结果
-- **权威 schema**：`https://fal.ai/models/<endpoint-id>/llms.txt`
-
-## 2. 能力清单
-
-| 能力 | endpoint id |
-|---|---|
-| 文生图 | `fal-ai/z-image/turbo` |
-| 图生图（单图 + 强度） | `fal-ai/z-image/turbo/image-to-image` |
-
-## 3. 请求参数（两个端点共有）
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `prompt` | string | 必填 | — | 生成描述 |
-| `image_size` | 枚举或对象 | 可选 | 文生图 `landscape_4_3`；图生图 `auto` | 枚举 `square_hd`、`square`、`portrait_4_3`、`portrait_16_9`、`landscape_4_3`、`landscape_16_9`（图生图还支持 `auto`），或 `{ width, height }` |
-| `num_inference_steps` | integer | 可选 | `8` | **1–8**。Turbo 模型步数很低 |
-| `seed` | integer | 可选 | 随机 | **本项目规则：绝对不显示**，不下发 |
-| `sync_mode` | boolean | 可选 | `false` | `true` 时以 data URI 返回且不入请求历史 |
-| `num_images` | integer | 可选 | `1` | **1–4** |
-| `enable_safety_checker` | boolean | 可选 | `true` | 关闭需账号授权；**被判定为不安全的图会返回黑图** |
-| `output_format` | string | 可选 | `png` | `jpeg` / `png` / `webp` |
-| `acceleration` | string | 可选 | `regular` | `none` / `regular` / `high` |
-| `enable_prompt_expansion` | boolean | 可选 | `false` | 提示词扩写。**每次请求加价 0.0025 credits** |
-
-**仅 `image-to-image` 有：**
-
-| 字段 | 类型 | 必填 | 默认 | 说明 |
-|---|---|---|---|---|
-| `image_url` | string | 必填 | — | **单张**输入图 URL（不是数组） |
-| `strength` | float | 可选 | `0.6` | 图生图条件强度 |
-
-## 4. 响应结构
-
-```json
-{
-  "images": [ { "url": "https://.../z-image-turbo-output.png", "content_type": "image/png", "width": 1024, "height": 768 } ],
-  "timings": { },
-  "seed": 42,
-  "has_nsfw_concepts": [false],
-  "prompt": "（实际用于生成的提示词）"
-}
-```
-
-`images`、`timings`、`seed`、`has_nsfw_concepts`、`prompt` 都是必返回字段。`images[]` 元素带 `content_type` / `width` / `height`，比其他供应商信息更全。
-
-## 5. 价格
-
-来源：两个端点的 `llms.txt`（2026-08-22 读取）。
-
-| 项 | 价格 |
-|---|---|
-| 基础 | **$0.005 / 百万像素（megapixel）** |
-| `enable_prompt_expansion: true` | 每次请求额外 **+0.0025 credits** |
-
-> Fal 这里按**像素面积**计价，与百炼（按张 0.1/0.2 元）、APIMart（按张 $0.01/$0.02）、KIE（按张 $0.004）的计价口径完全不同。1024×1024 约 1.05 MP，折合约 $0.00524/张。
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点**有 `seed`**（不下发），无负面提示词字段。
-- `output_format`、`sync_mode` 按项目约定不展示、不请求；`acceleration` 与 `num_inference_steps` 是已公开的成本/速度控制，SDK 保留为可选参数。
-- SDK 新增独立 `falZImageTurboImageSize` 请求档：默认 `provider` 保持 0.1.5 的长边 1K/2K 语义，显式 `1MP` 则按比例发送约 1024²、16 对齐的对象，供需要精确复刻旧插件尺寸语义的 adapter 使用。
-- 这是唯一有图生图的 Z-Image 供应商，`image_url` 是**单张字符串**，不是数组。
-- `num_images` 最多 4（其他供应商固定 1），是否开放由产品决定。
-- 关闭安全检查时不安全图会返回**黑图**而不是报错，结果解析要能识别。
-- 计价按像素面积，成本估算逻辑不能沿用「按张」的模型。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| 文生图模型页 | https://fal.ai/models/fal-ai/z-image/turbo | 否 |
-| 文生图 schema + 价格 | https://fal.ai/models/fal-ai/z-image/turbo/llms.txt | 否 |
-| 图生图模型页 | https://fal.ai/models/fal-ai/z-image/turbo/image-to-image | 否 |
-| 图生图 schema + 价格 | https://fal.ai/models/fal-ai/z-image/turbo/image-to-image/llms.txt | 否 |
-| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
-| API Key 创建 | https://fal.ai/dashboard/keys | **是** |
+# Z-Image Turbo · Fal
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-11-08 |
+| 模态 | 图片 |
+| 供应商 | fal.ai（聚合平台） |
+| 平台模型 ID | `fal-ai/z-image/turbo`、`fal-ai/z-image/turbo/image-to-image` |
+| 接口形态 | 队列异步（推荐）或同步直连 |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> **Fal 是唯一提供 Z-Image 图生图能力的供应商**（百炼官方、APIMart、KIE 都只有文生图）。
+
+## 1. 接入协议（Fal 通用）
+
+- **鉴权**：`Authorization: Key $FAL_KEY`
+- **同步**：`POST https://fal.run/<endpoint-id>`
+- **队列**：`POST https://queue.fal.run/<endpoint-id>` → `{ request_id, status_url, response_url, cancel_url }`；`GET .../requests/{id}/status`（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`）；`GET .../requests/{id}` 取结果
+- **权威 schema**：`https://fal.ai/models/<endpoint-id>/llms.txt`
+
+## 2. 能力清单
+
+| 能力 | endpoint id |
+|---|---|
+| 文生图 | `fal-ai/z-image/turbo` |
+| 图生图（单图 + 强度） | `fal-ai/z-image/turbo/image-to-image` |
+
+## 3. 请求参数（两个端点共有）
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `prompt` | string | 必填 | — | 生成描述 |
+| `image_size` | 枚举或对象 | 可选 | 文生图 `landscape_4_3`；图生图 `auto` | 枚举 `square_hd`、`square`、`portrait_4_3`、`portrait_16_9`、`landscape_4_3`、`landscape_16_9`（图生图还支持 `auto`），或 `{ width, height }` |
+| `num_inference_steps` | integer | 可选 | `8` | **1–8**。Turbo 模型步数很低 |
+| `seed` | integer | 可选 | 随机 | **本项目规则：绝对不显示**，不下发 |
+| `sync_mode` | boolean | 可选 | `false` | `true` 时以 data URI 返回且不入请求历史 |
+| `num_images` | integer | 可选 | `1` | **1–4** |
+| `enable_safety_checker` | boolean | 可选 | `true` | 关闭需账号授权；**被判定为不安全的图会返回黑图** |
+| `output_format` | string | 可选 | `png` | `jpeg` / `png` / `webp` |
+| `acceleration` | string | 可选 | `regular` | `none` / `regular` / `high` |
+| `enable_prompt_expansion` | boolean | 可选 | `false` | 提示词扩写。**每次请求加价 0.0025 credits** |
+
+**仅 `image-to-image` 有：**
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `image_url` | string | 必填 | — | **单张**输入图 URL（不是数组） |
+| `strength` | float | 可选 | `0.6` | 图生图条件强度 |
+
+## 4. 响应结构
+
+```json
+{
+  "images": [ { "url": "https://.../z-image-turbo-output.png", "content_type": "image/png", "width": 1024, "height": 768 } ],
+  "timings": { },
+  "seed": 42,
+  "has_nsfw_concepts": [false],
+  "prompt": "（实际用于生成的提示词）"
+}
+```
+
+`images`、`timings`、`seed`、`has_nsfw_concepts`、`prompt` 都是必返回字段。`images[]` 元素带 `content_type` / `width` / `height`，比其他供应商信息更全。
+
+## 5. 价格
+
+来源：两个端点的 `llms.txt`（2026-08-22 读取）。
+
+| 项 | 价格 |
+|---|---|
+| 基础 | **$0.005 / 百万像素（megapixel）** |
+| `enable_prompt_expansion: true` | 每次请求额外 **+0.0025 credits** |
+
+> Fal 这里按**像素面积**计价，与百炼（按张 0.1/0.2 元）、APIMart（按张 $0.01/$0.02）、KIE（按张 $0.004）的计价口径完全不同。1024×1024 约 1.05 MP，折合约 $0.00524/张。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。Fal 本端点**有 `seed`**（不下发），无负面提示词字段。
+- `output_format`、`sync_mode` 按项目约定不展示、不请求；`acceleration` 与 `num_inference_steps` 是已公开的成本/速度控制，SDK 保留为可选参数。
+- SDK 新增独立 `falZImageTurboImageSize` 请求档：默认 `provider` 保持 0.1.5 的长边 1K/2K 语义，显式 `1MP` 则按比例发送约 1024²、16 对齐的对象，供需要精确复刻旧插件尺寸语义的 adapter 使用。
+- 这是唯一有图生图的 Z-Image 供应商，`image_url` 是**单张字符串**，不是数组。
+- `num_images` 最多 4（其他供应商固定 1），是否开放由产品决定。
+- 关闭安全检查时不安全图会返回**黑图**而不是报错，结果解析要能识别。
+- 计价按像素面积，成本估算逻辑不能沿用「按张」的模型。
+
+- 界面与请求一致（2026-11-08“所选即所发”离线检查）：选 1MP，或带图且比例为智能（image_size=auto）时不看分辨率，分辨率参数隐藏。
+
+- 官方格式核对（2026-11-08）：强度下限按官方“大于 0”改为 0.05，旧工程存的 0 由联动改为 0.05；选 1MP 时按一百万像素计价。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| 文生图模型页 | https://fal.ai/models/fal-ai/z-image/turbo | 否 |
+| 文生图 schema + 价格 | https://fal.ai/models/fal-ai/z-image/turbo/llms.txt | 否 |
+| 图生图模型页 | https://fal.ai/models/fal-ai/z-image/turbo/image-to-image | 否 |
+| 图生图 schema + 价格 | https://fal.ai/models/fal-ai/z-image/turbo/image-to-image/llms.txt | 否 |
+| 队列协议 | https://fal.ai/docs/documentation/model-apis/inference/queue | 否 |
+| API Key 创建 | https://fal.ai/dashboard/keys | **是** |
+
+## 2026-11-08 官方格式核对
+
+图生图 `strength` 官方取值大于 0、不超过 1，界面下限 0.05、构建时夹紧，参数静态下限仍为 0 以兼容旧工程（2026-11-08 按官方 OpenAPI 核对）。来源：https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=<端点>（无需登录）。

package/docs/model-adaptation/Z-Image-Turbo/Z-Image-Turbo_KIE.md

@@ -1,71 +1,71 @@
-# Z-Image Turbo · KIE
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-22 |
-| 模态 | 图片 |
-| 供应商 | KIE.ai（聚合平台） |
-| 平台模型 ID | `z-image` |
-| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-> KIE 的 model 名是 **`z-image`**（不带 `-turbo`），定价页条目名为 `Qwen z-image`。
-
-## 1. 接入协议
-
-- **Base URL**：`https://api.kie.ai`
-- **鉴权**：`Authorization: Bearer <API_KEY>`
-- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: "z-image", callBackUrl?, input }`
-- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
-- **终态**：`state` ∈ `waiting` / `queuing` / `generating` / `success` / `fail`
-- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: [...] }`；失败读 `failCode` / `failMsg`
-
-## 2. 能力清单
-
-仅**文生图**一个端点 `z-image`。
-
-## 3. 请求参数
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `model` | string | 必填 | `z-image` | 必须是 `z-image` |
-| `input.prompt` | string | 必填 | — | **最长 1000 字符**（官方百炼是 800，APIMart 是 800） |
-| `input.aspect_ratio` | string | 必填 | `1:1` | **只有 5 个**：`1:1`、`4:3`、`3:4`、`16:9`、`9:16` |
-| `input.nsfw_checker` | boolean | 可选 | `false` | `false` 时关闭内容过滤，结果直接返回 |
-
-> ⚠️ **文档自相矛盾**：`aspect_ratio` 的描述文字写了「选择 `auto` 可匹配首张输入图像的比例（需传入输入图像）」，但枚举里**没有 `auto`**，`input` 中也**没有输入图字段**。这段描述应属复制粘贴残留，接入时按枚举的 5 个比例处理，不要下发 `auto`。
-
-**没有分辨率档位参数**（无 `resolution` / `size`），也**没有 `prompt_extend`**——这两点与百炼官方和 APIMart 都不同。
-
-## 4. 响应结构
-
-`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://..."] }`。
-
-## 5. 价格
-
-来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `z-image`；1 Credit = $0.005）。
-
-| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
-|---|---|---|---|---|
-| `Qwen z-image`, text-to-image, 1.0s | 0.8 /张 | **$0.004/张** | $0.005 | 20% |
-
-KIE 只有一个价格档，不区分分辨率，也不区分是否开启提示词改写。
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
-- 比例集合只有 5 个，是所有供应商里最少的；跨供应商共享比例集合时必须按供应商裁剪。
-- 没有分辨率档位，输出尺寸完全由比例决定，UI 不要出现 1K/2K 选择。
-- 提示词上限 1000 字符（与另两家的 800 不同）。
-- `resultJson` 是 JSON 字符串，必须二次 parse。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| z-image 生成端点 | https://docs.kie.ai/cn/market/z-image/z-image | 否 |
-| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
-| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
-| 定价页（搜 `z-image`） | https://kie.ai/pricing | 否 |
-| API Key 管理 | https://kie.ai/api-key | **是** |
+# Z-Image Turbo · KIE
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 图片 |
+| 供应商 | KIE.ai（聚合平台） |
+| 平台模型 ID | `z-image` |
+| 接口形态 | **异步任务**（`createTask` + `recordInfo`） |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+> KIE 的 model 名是 **`z-image`**（不带 `-turbo`），定价页条目名为 `Qwen z-image`。
+
+## 1. 接入协议
+
+- **Base URL**：`https://api.kie.ai`
+- **鉴权**：`Authorization: Bearer <API_KEY>`
+- **提交**：`POST /api/v1/jobs/createTask`，体为 `{ model: "z-image", callBackUrl?, input }`
+- **查询**：`GET /api/v1/jobs/recordInfo?taskId=...`
+- **终态**：`state` ∈ `waiting` / `queuing` / `generating` / `success` / `fail`
+- **结果**：`JSON.parse(resultJson)` → `{ resultUrls: [...] }`；失败读 `failCode` / `failMsg`
+
+## 2. 能力清单
+
+仅**文生图**一个端点 `z-image`。
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必填 | `z-image` | 必须是 `z-image` |
+| `input.prompt` | string | 必填 | — | **最长 1000 字符**（官方百炼是 800，APIMart 是 800） |
+| `input.aspect_ratio` | string | 必填 | `1:1` | **只有 5 个**：`1:1`、`4:3`、`3:4`、`16:9`、`9:16` |
+| `input.nsfw_checker` | boolean | 可选 | `false` | `false` 时关闭内容过滤，结果直接返回 |
+
+> ⚠️ **文档自相矛盾**：`aspect_ratio` 的描述文字写了「选择 `auto` 可匹配首张输入图像的比例（需传入输入图像）」，但枚举里**没有 `auto`**，`input` 中也**没有输入图字段**。这段描述应属复制粘贴残留，接入时按枚举的 5 个比例处理，不要下发 `auto`。
+
+**没有分辨率档位参数**（无 `resolution` / `size`），也**没有 `prompt_extend`**——这两点与百炼官方和 APIMart 都不同。
+
+## 4. 响应结构
+
+`state=success` 后 `JSON.parse(resultJson)` → `{ "resultUrls": ["https://..."] }`。
+
+## 5. 价格
+
+来源：[KIE 定价页](https://kie.ai/pricing)（2026-08-22 读取，搜索 `z-image`；1 Credit = $0.005）。
+
+| 规格 | 积分 | 我们的价格 | 官方 / Fal 参考价 | 节省 |
+|---|---|---|---|---|
+| `Qwen z-image`, text-to-image, 1.0s | 0.8 /张 | **$0.004/张** | $0.005 | 20% |
+
+KIE 只有一个价格档，不区分分辨率，也不区分是否开启提示词改写。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。KIE 本接口两个字段都没有。
+- 比例集合只有 5 个，是所有供应商里最少的；跨供应商共享比例集合时必须按供应商裁剪。
+- 没有分辨率档位，输出尺寸完全由比例决定，UI 不要出现 1K/2K 选择。
+- 提示词上限 1000 字符（与另两家的 800 不同）。
+- `resultJson` 是 JSON 字符串，必须二次 parse。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| z-image 生成端点 | https://docs.kie.ai/cn/market/z-image/z-image | 否 |
+| 获取任务详情 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 通用 API 快速入门 | https://docs.kie.ai/cn/common-api/quickstart | 否 |
+| 定价页（搜 `z-image`） | https://kie.ai/pricing | 否 |
+| API Key 管理 | https://kie.ai/api-key | **是** |

package/docs/model-adaptation/Z-Image-Turbo/Z-Image-Turbo_/347/231/276/347/202/274.md

@@ -1,122 +1,122 @@
-# Z-Image Turbo · 百炼（阿里云百炼，官方）
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-22 |
-| 模态 | 图片 |
-| 供应商 | 阿里云百炼（Model Studio / DashScope），模型原厂官方接口 |
-| 平台模型 ID | `z-image-turbo` |
-| 接口形态 | **HTTP 同步调用** |
-| 文档可见性 | 公开，无需登录 |
-| 价格可见性 | 公开，无需登录 |
-
-模型定位：轻量级**文生图**模型，快速出图，支持中英文字渲染，灵活适配多种分辨率与宽高比。
-
-| 模型 | 简介 | 输出图像规格 |
-|---|---|---|
-| `z-image-turbo` | 轻量模型，快速生图 | 分辨率：总像素 `[512*512, 2048*2048]`；格式 **PNG**；**张数固定 1 张** |
-
-## 1. 接入协议
-
-`POST https://{WorkspaceId}.<region>.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
-
-| 地域 | `<region>` |
-|---|---|
-| 华北 2（北京） | `cn-beijing` |
-| 新加坡 | `ap-southeast-1` |
-
-旧域名 `https://dashscope.aliyuncs.com` / `https://dashscope-intl.aliyuncs.com` 仍可用。`{WorkspaceId}` 在百炼控制台业务空间详情页查看。
-
-请求头：`Content-Type: application/json`、`Authorization: Bearer sk-xxxx`。
-
-**结果时效**：图像 URL **仅保留 24 小时**，超时自动清除。
-
-## 2. 能力清单
-
-仅**文生图**一种能力。`content` 数组**必须且只能包含 1 个 `text` 对象**，不传或传多个会报错。**当前仅支持单轮对话**（`messages` 只能一组 role/content）。
-
-Z-Image 在百炼官方**没有图生图 / 图像编辑端点**。
-
-## 3. 请求参数
-
-| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
-|---|---|---|---|---|
-| `model` | string | 必选 | — | 必须为 `z-image-turbo` |
-| `input.messages[0].role` | string | 必选 | — | 固定 `user` |
-| `input.messages[0].content[0].text` | string | 必选 | — | 正向提示词。支持中英文，**长度不超过 800 个字符**（每个汉字、字母、数字或符号计 1 个字符），超出自动截断 |
-| `parameters.size` | string | 可选 | `1024*1536` | 格式 `宽*高`。总像素须在 `[512*512, 2048*2048]`；**推荐总像素在 `[1024*1024, 1536*1536]` 之间效果更佳** |
-| `parameters.prompt_extend` | bool | 可选 | `false` | 智能提示词改写。**直接影响费用：`true` 的价格是 `false` 的 2 倍**。开启后额外返回改写后的提示词与思考过程，并增加响应时间 |
-| `parameters.seed` | integer | 可选 | 随机 | `[0, 2147483647]`。**本项目规则：绝对不显示**，不下发 |
-
-### 官方推荐分辨率（按总像素档）
-
-**总像素 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`
-
-> 官方给出 **11 种比例**（含 7:9、9:7、9:21），比任何聚合平台都多。
-
-## 4. 响应结构
-
-```json
-{
-  "output": { "choices": [ { "finish_reason": "stop", "message": {
-    "content": [ { "image": "https://dashscope-result-bj...png?Expires=..." },
-                 { "text": "（prompt_extend=false 时为原提示词；true 时为改写后提示词）" } ],
-    "reasoning_content": "", "role": "assistant" } } ] },
-  "usage": { "height": 1440, "image_count": 1, "input_tokens": 0, "output_tokens": 0, "total_tokens": 0, "width": 1120 },
-  "request_id": "..."
-}
-```
-
-| 字段 | 说明 |
-|---|---|
-| `output.choices[].message.content[].image` | 生成图像 URL，**PNG**，24 小时有效 |
-| `output.choices[].message.content[].text` | `prompt_extend=false` 时为输入提示词；`true` 时为改写后提示词 |
-| `output.choices[].message.reasoning_content` | 思考过程，**仅 `prompt_extend=true` 时返回** |
-| `usage.width` / `usage.height` | 输出图宽高 |
-| `usage.image_count` | 固定为 1 |
-| `usage.input_tokens` / `output_tokens` / `total_tokens` | `prompt_extend=false` 时固定为 0 |
-| `usage.output_tokens_details.reasoning_tokens` | 仅 `prompt_extend=true` 时返回 |
-
-**失败**：返回 `request_id`、`code`、`message`，例如 `{"code":"InvalidParameter","message":"num_images_per_prompt must be 1"}`。内容审核不通过会报 `IPInfringementSuspect` 或 `DataInspectionFailed`。
-
-## 5. 价格（官方，人民币）
-
-来源：[百炼模型价格](https://help.aliyun.com/zh/model-studio/model-pricing)（2026-08-22 读取）。
-
-**华北 2（北京）**
-
-| 模型 | 单价 | 免费额度 |
-|---|---|---|
-| `z-image-turbo` | `prompt_extend=false`：**0.1 元/张**<br>`prompt_extend=true`：**0.2 元/张** | 100 张 |
-
-**新加坡（国际）**
-
-| 模型 | 单价 |
-|---|---|
-| `z-image-turbo` | `false`：0.110089 元/张；`true`：0.220177 元/张 |
-
-按**成功生成的图像张数**计费；调用失败或处理错误不产生费用，也不消耗免费额度。免费额度有效期为开通百炼 / 模型发布 / 申请通过之日起 90 天内（以较晚者为准）。
-
-## 6. 适配要点
-
-- 本项目默认**绝对不显示**：`seed`、负面提示词。官方有 `seed`（不下发），无负面提示词字段。
-- `prompt_extend` **直接翻倍计费**，若要暴露给用户必须在 UI 上说明，或固定为 `false`。
-- `size` 分隔符是 `*` 不是 `x`。
-- 固定出 1 张，UI 不要出现数量选择。
-- 输出固定 PNG，无 `output_format`。
-- 提示词硬上限 800 字符且**超出静默截断**，前端应做长度提示。
-- 官方仅文生图，本模型如果要在项目里支持图生图，只能走 Fal 的 `image-to-image` 端点。
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 是否需登录 |
-|---|---|---|
-| Z-Image API 参考（参数、响应、限制、计费） | https://help.aliyun.com/zh/model-studio/z-image-api-reference | 否 |
-| 用户清单给出的控制台入口（同内容） | https://bailian.console.aliyun.com/cn-beijing?tab=api#/api/?type=model&url=3002354 | **是**（控制台）；公开页见上一行 |
-| 模型价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
-| 各地域支持的模型列表 | https://help.aliyun.com/zh/model-studio/models | 否 |
-| API Key 获取 | https://bailian.console.aliyun.com/?apiKey=1#/api-key | **是** |
+# Z-Image Turbo · 百炼（阿里云百炼，官方）
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-08-22 |
+| 模态 | 图片 |
+| 供应商 | 阿里云百炼（Model Studio / DashScope），模型原厂官方接口 |
+| 平台模型 ID | `z-image-turbo` |
+| 接口形态 | **HTTP 同步调用** |
+| 文档可见性 | 公开，无需登录 |
+| 价格可见性 | 公开，无需登录 |
+
+模型定位：轻量级**文生图**模型，快速出图，支持中英文字渲染，灵活适配多种分辨率与宽高比。
+
+| 模型 | 简介 | 输出图像规格 |
+|---|---|---|
+| `z-image-turbo` | 轻量模型，快速生图 | 分辨率：总像素 `[512*512, 2048*2048]`；格式 **PNG**；**张数固定 1 张** |
+
+## 1. 接入协议
+
+`POST https://{WorkspaceId}.<region>.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation`
+
+| 地域 | `<region>` |
+|---|---|
+| 华北 2（北京） | `cn-beijing` |
+| 新加坡 | `ap-southeast-1` |
+
+旧域名 `https://dashscope.aliyuncs.com` / `https://dashscope-intl.aliyuncs.com` 仍可用。`{WorkspaceId}` 在百炼控制台业务空间详情页查看。
+
+请求头：`Content-Type: application/json`、`Authorization: Bearer sk-xxxx`。
+
+**结果时效**：图像 URL **仅保留 24 小时**，超时自动清除。
+
+## 2. 能力清单
+
+仅**文生图**一种能力。`content` 数组**必须且只能包含 1 个 `text` 对象**，不传或传多个会报错。**当前仅支持单轮对话**（`messages` 只能一组 role/content）。
+
+Z-Image 在百炼官方**没有图生图 / 图像编辑端点**。
+
+## 3. 请求参数
+
+| 字段 | 类型 | 必填 | 默认 | 取值与说明 |
+|---|---|---|---|---|
+| `model` | string | 必选 | — | 必须为 `z-image-turbo` |
+| `input.messages[0].role` | string | 必选 | — | 固定 `user` |
+| `input.messages[0].content[0].text` | string | 必选 | — | 正向提示词。支持中英文，**长度不超过 800 个字符**（每个汉字、字母、数字或符号计 1 个字符），超出自动截断 |
+| `parameters.size` | string | 可选 | `1024*1536` | 格式 `宽*高`。总像素须在 `[512*512, 2048*2048]`；**推荐总像素在 `[1024*1024, 1536*1536]` 之间效果更佳** |
+| `parameters.prompt_extend` | bool | 可选 | `false` | 智能提示词改写。**直接影响费用：`true` 的价格是 `false` 的 2 倍**。开启后额外返回改写后的提示词与思考过程，并增加响应时间 |
+| `parameters.seed` | integer | 可选 | 随机 | `[0, 2147483647]`。**本项目规则：绝对不显示**，不下发 |
+
+### 官方推荐分辨率（按总像素档）
+
+**总像素 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`
+
+> 官方给出 **11 种比例**（含 7:9、9:7、9:21），比任何聚合平台都多。
+
+## 4. 响应结构
+
+```json
+{
+  "output": { "choices": [ { "finish_reason": "stop", "message": {
+    "content": [ { "image": "https://dashscope-result-bj...png?Expires=..." },
+                 { "text": "（prompt_extend=false 时为原提示词；true 时为改写后提示词）" } ],
+    "reasoning_content": "", "role": "assistant" } } ] },
+  "usage": { "height": 1440, "image_count": 1, "input_tokens": 0, "output_tokens": 0, "total_tokens": 0, "width": 1120 },
+  "request_id": "..."
+}
+```
+
+| 字段 | 说明 |
+|---|---|
+| `output.choices[].message.content[].image` | 生成图像 URL，**PNG**，24 小时有效 |
+| `output.choices[].message.content[].text` | `prompt_extend=false` 时为输入提示词；`true` 时为改写后提示词 |
+| `output.choices[].message.reasoning_content` | 思考过程，**仅 `prompt_extend=true` 时返回** |
+| `usage.width` / `usage.height` | 输出图宽高 |
+| `usage.image_count` | 固定为 1 |
+| `usage.input_tokens` / `output_tokens` / `total_tokens` | `prompt_extend=false` 时固定为 0 |
+| `usage.output_tokens_details.reasoning_tokens` | 仅 `prompt_extend=true` 时返回 |
+
+**失败**：返回 `request_id`、`code`、`message`，例如 `{"code":"InvalidParameter","message":"num_images_per_prompt must be 1"}`。内容审核不通过会报 `IPInfringementSuspect` 或 `DataInspectionFailed`。
+
+## 5. 价格（官方，人民币）
+
+来源：[百炼模型价格](https://help.aliyun.com/zh/model-studio/model-pricing)（2026-08-22 读取）。
+
+**华北 2（北京）**
+
+| 模型 | 单价 | 免费额度 |
+|---|---|---|
+| `z-image-turbo` | `prompt_extend=false`：**0.1 元/张**<br>`prompt_extend=true`：**0.2 元/张** | 100 张 |
+
+**新加坡（国际）**
+
+| 模型 | 单价 |
+|---|---|
+| `z-image-turbo` | `false`：0.110089 元/张；`true`：0.220177 元/张 |
+
+按**成功生成的图像张数**计费；调用失败或处理错误不产生费用，也不消耗免费额度。免费额度有效期为开通百炼 / 模型发布 / 申请通过之日起 90 天内（以较晚者为准）。
+
+## 6. 适配要点
+
+- 本项目默认**绝对不显示**：`seed`、负面提示词。官方有 `seed`（不下发），无负面提示词字段。
+- `prompt_extend` **直接翻倍计费**，若要暴露给用户必须在 UI 上说明，或固定为 `false`。
+- `size` 分隔符是 `*` 不是 `x`。
+- 固定出 1 张，UI 不要出现数量选择。
+- 输出固定 PNG，无 `output_format`。
+- 提示词硬上限 800 字符且**超出静默截断**，前端应做长度提示。
+- 官方仅文生图，本模型如果要在项目里支持图生图，只能走 Fal 的 `image-to-image` 端点。
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 是否需登录 |
+|---|---|---|
+| Z-Image API 参考（参数、响应、限制、计费） | https://help.aliyun.com/zh/model-studio/z-image-api-reference | 否 |
+| 用户清单给出的控制台入口（同内容） | https://bailian.console.aliyun.com/cn-beijing?tab=api#/api/?type=model&url=3002354 | **是**（控制台）；公开页见上一行 |
+| 模型价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
+| 各地域支持的模型列表 | https://help.aliyun.com/zh/model-studio/models | 否 |
+| API Key 获取 | https://bailian.console.aliyun.com/?apiKey=1#/api-key | **是** |