z-image-turbo 图片生成 Skill
通过 Gitee AI 的 OpenAI-compatible Images API 调用 z-image-turbo 模型：
- Endpoint:
https://ai.gitee.com/v1/images/generations - Model:
z-image-turbo - 认证：环境变量
API_TOKEN - 请求方式：
POST - 请求类型：
application/json
使用前检查
确保已经设置 API Token：
export API_TOKEN="your-gitee-api-token"
不要把 token 写入 prompt、文件、日志或代码，也不要在回复中展示 token。
支持的尺寸
size 只能使用以下值：
2048x20482048x15361536x20482048x13601360x20482048x11521152x2048
如果调用方只给出宽高，优先将其映射到上述尺寸；无法精确匹配时，选择比例最接近的尺寸，并告知调用方实际使用的尺寸。也可以使用 API 支持的 width 和 height 字段，但生成任务应优先传入合法的 size。
标准文生图调用
curl https://ai.gitee.com/v1/images/generations \
-X POST \
-H "Content-Type: application/json" \
-H "X-Failover-Enabled: true" \
-H "Authorization: Bearer $API_TOKEN" \
-d '{
"prompt": "A robot sitting on open grassland, painting on a canvas.",
"model": "z-image-turbo",
"size": "1024x1024",
"num_images_per_prompt": 0,
"negative_prompt": "blurry, ugly, bad",
"num_inference_steps": 9,
"seed": 0,
"lora_weights": [],
"lora_scale": 0
}'
注意：上面的 1024x1024 是接口示例中的值；本服务当前推荐/支持的尺寸列表见上文。实际调用时应使用列表中的尺寸，例如 2048x2048。
常用请求字段
| 字段 | 类型 | 说明 |
|---|---|---|
prompt |
string | 必填，图片内容描述。尽量明确主体、动作、构图、风格、光线和文字排版要求。 |
model |
string | 必填，固定为 z-image-turbo。 |
size |
string | 推荐使用的输出尺寸，必须是支持的尺寸之一。 |
width / height |
integer | 可选，宽高参数；通常由 size 控制。示例中可传 0。 |
negative_prompt |
string | 可选，要求避免的内容，例如 blurry, low quality, distorted hands。 |
num_images_per_prompt |
integer | 每个 prompt 的图片数量；按接口示例传 0，若服务端拒绝该值则改为 1。 |
num_inference_steps |
integer | 推理步数，z-image-turbo 示例使用 9。 |
seed |
integer | 随机种子；使用 0 表示由服务端处理或采用默认随机行为。 |
guidance_scale |
number | 可选，引导强度；示例值为 1。 |
lora_weights |
array | 可选，LoRA 权重列表；无 LoRA 时传 []。 |
lora_scale |
number | 可选，LoRA 强度；无 LoRA 时传 0。 |
image_scale |
number | 可选，控制图相关的图像缩放，示例值为 1。 |
使用控制图（HED）
control_image 需要传入图片的 base64 编码字符串；不要直接传本地文件路径。示例：
curl https://ai.gitee.com/v1/images/generations \
-X POST \
-H "Content-Type: application/json" \
-H "X-Failover-Enabled: true" \
-H "Authorization: Bearer $API_TOKEN" \
-d '{
"prompt": "A woman dressed in casual denim jeans and a fitted tank top standing in the vibrant cityscape of Dubai.",
"model": "z-image-turbo",
"size": "2048x1536",
"num_images_per_prompt": 0,
"negative_prompt": "blurry, ugly, bad",
"num_inference_steps": 9,
"seed": 0,
"guidance_scale": 1,
"control_image": "<BASE64_IMAGE_DATA>",
"control_mode": "HED",
"control_context_scale": 0.75,
"image_scale": 1
}'
生成 base64 的示例：
CONTROL_IMAGE=$(base64 -w 0 input.png)
然后在 JSON 中使用环境变量或由程序安全注入，避免手工拼接超长字符串导致 JSON 转义错误。control_mode 使用 HED 时应同时提供 control_image；control_context_scale 示例值为 0.75。
调用规则
- 根据用户需求编写或整理
prompt，保留用户指定的主体、风格、构图和文字内容。 - 默认使用
model: "z-image-turbo"、num_inference_steps: 9、seed: 0。 - 用户未指定尺寸时使用
2048x2048；指定比例时从支持列表中选择最接近的尺寸。 - 用户指定负面要求时填入
negative_prompt，不要把负面要求重复堆入正向 prompt。 - 只有在用户提供控制图且确实需要结构约束时才传
control_image、control_mode和相关字段。 - 请求失败时先检查
API_TOKEN、JSON 格式、model、size和num_images_per_prompt，再重试；不要无意义地重复请求。 - 成功后解析 API 返回的图片 URL 或图片数据，并向调用方返回结果；如接口返回任务 ID，应继续按服务响应约定查询任务状态。
安全与质量提示
- 不要伪造接口成功结果；必须以 API 实际响应为准。
- 生成海报或包含大量文字的图片时，在 prompt 中明确要求文字原样、字体、位置和层级，但应提醒调用方图像模型可能出现文字拼写误差。
- 对涉及真实人物、版权角色或敏感内容的请求，遵守上层安全政策和服务端限制。
- 发生 HTTP 错误时保留状态码和服务端错误信息的摘要，隐藏 Authorization 头和 token。
