z-image-turbo 图像生成

问题背景

调用文生图 API 时，开发者常遇到尺寸参数格式不统一导致请求被拒、负面提示与正向描述重复堆砌影响生成质量、控制图接口要求 base64 编码但手工拼接易引发 JSON 转义错误等问题。这些问题增加调试成本，参数错误还可能导致任务失败。

工作原理

该技能通过封装 Gitee AI 的 OpenAI 兼容接口，将复杂参数处理转化为标准化操作流程。核心能力包括：

• 尺寸智能映射：自动将用户指定的宽高比例匹配到 2048x2048、2048x1536 等支持的固定尺寸，无法精确匹配时选择最接近比例并明确告知实际尺寸
• 参数安全注入：通过环境变量注入 API Token，避免 token 泄露到日志或代码中；控制图参数采用 base64 字符串安全注入，避免手工拼接超长字符串
• 负面提示分离：将用户负面要求单独填入 negative_prompt 字段，避免与正向描述重复堆砌
• 控制图支持：通过 control_image 参数传入 HED 控制图，配合 control_mode 和 control_context_scale 实现结构化约束

关键步骤包括：环境变量检查确保 API_TOKEN 已设置 → 尺寸参数映射与默认值应用 → prompt 整理与负面提示分离 → 请求构建与参数安全注入 → API 响应解析与错误处理。接口返回任务 ID 时，需按服务响应约定继续查询任务状态直至完成。

注意事项

• Token 安全：API_TOKEN 必须通过环境变量注入，禁止写入代码、日志或 prompt
• 尺寸合规：所有尺寸参数必须严格匹配支持的 7 种固定尺寸，调用方未指定时默认使用 2048x2048
• 负面提示规范：负面要求仅填入 negative_prompt，正向 prompt 需保留用户指定的主体、风格、构图等核心要素
• 控制图使用：仅在用户明确需要结构约束时传递控制图参数，避免过度约束影响生成自由度
• 错误处理：请求失败时需检查 token 有效性、JSON 格式、model/size 参数合法性，HTTP 错误需保留状态码但隐藏 Authorization 头
• 文字生成风险：生成海报等含大量文字的图片时，需在 prompt 中明确文字要求，但需提醒调用方图像模型可能存在拼写误差
• 敏感内容管控：涉及真实人物、版权角色或敏感内容时，需遵守上层安全政策和服务端限制