KIE.ai 图像生成

使用 KIE.ai 的 GPT-Image-2 模型，通过文本提示生成图像，或对现有图像进行变换。

前提条件

• KIE.ai API 密钥：所有操作均需该密钥。请前往 https://kie.ai 获取
• API 密钥必须存储在环境变量 KIE_API_KEY 中，或由用户显式提供

快速开始

文本生成图像（Text-to-Image）

python scripts/kie_image.py --mode text2img --prompt "YOUR_PROMPT" --api-key YOUR_KEY --output ./output

图像生成图像（Image-to-Image）

python scripts/kie_image.py --mode img2img --prompt "YOUR_PROMPT" --input-urls "URL1,URL2" --api-key YOUR_KEY --output ./output

工作流程

步骤 1：确定运行模式

• text2img：用户仅提供文本提示 → 使用 gpt-image-2-text-to-image
• img2img：用户同时提供源图像和文本提示 → 使用 gpt-image-2-image-to-image

若用户提供参考图像（上传的文件、URL 或本地路径），则启用 img2img 模式。

步骤 2：准备参数

提示词编写建议：

• 尽量具体、详尽，以获得最佳效果
• 可包含风格、光照、构图等细节描述
• 在 img2img 场景中，应明确说明输出图像与输入图像之间的关系

宽高比使用指南：

• auto（默认）：由模型自动决定
• 1:1：正方形，适用于人像、图标等
• 16:9：横屏比例，适用于宽幅场景
• 9:16：竖屏比例，适用于手机屏幕、海报等
• 4:3/3:4：标准照片比例

步骤 3：执行脚本

Python 脚本（scripts/kie_image.py）将完成以下操作：

1. 在 KIE.ai 上创建任务
2. 轮询任务状态直至完成（最长等待 5 分钟）
3. 将生成的图像下载至指定输出目录
4. 输出包含文件路径的 JSON 结果

API 密钥解析优先级：

1. --api-key 命令行参数
2. KIE_API_KEY 环境变量
3. 向用户请求其 API 密钥

步骤 4：展示结果

脚本将 JSON 格式结果输出至标准输出（stdout）：

{
  "task_id": "task_gptimage_xxx",
  "model": "gpt-image-2-text-to-image",
  "image_urls": ["https://..."],
  "downloaded_files": ["/path/to/image.png"],
  "status": "success"
}

请通过 open_result_view 或 preview_url 向用户展示生成的图像。

img2img 模式下源图像的处理

当用户为 img2img 模式提供本地图像文件时：

• 本地文件需先上传，获取公开可访问的 URL
• 可使用图床服务（如 Imgur 等）获取公开 URL
• input_urls 参数仅接受 HTTP/HTTPS 协议的 URL，不支持本地文件路径

错误处理

• 任务创建失败：请检查 API 密钥有效性、模型名称是否正确、参数格式是否合规
• 轮询超时：任务可能仍在处理中；用户可稍后使用 task ID 重试
• 结果中无图像 URL：API 响应结构可能发生变化；请检查完整输出内容
• 下载失败：图像 URL 可能具有时效性；建议在任务完成后立即下载

API 参考文档

详细 API 文档请参阅 references/api_reference.md。