5.4 KiB

Raw Blame History

name	description
ai-image	Generate images via AI text-to-image API (GPT Image / Grok). Use when the user asks to draw, paint, generate, or create an image from a text description.

AI 绘图工具

通过 FastAPI 文生图服务生成图片，供 Agent 通过 HTTP/cURL 直接调用，无需自己实现模型请求逻辑。

服务端使用 OpenAI Python SDK 请求 GPT Image / Grok Image 上游接口，生成的图片保存在服务端 output/<profile_name>/ 目录，并通过 HTTP 返回访问地址。

可用脚本

能力	服务端文件	HTTP 端点	模型
GPT / Grok 绘图	`agent-image-t2i.py`	`POST /images/generations`	`gpt-image-2-1K` / `gpt-image-2-2K` / `gpt-image-2-4K` / `grok-imagine-image-lite`
健康检查	`agent-image-t2i.py`	`GET /health`	—
图片访问	`agent-image-t2i.py`	`GET /output/{profile_name}/{filename}`	—

GPT 模型说明

模型	输出尺寸	备注
`gpt-image-2-1K`	~1254×1254（1:1）或 1536×1024（横版）	推荐，线路稳定
`gpt-image-2-2K`	不固定	线路不稳定，可能 503
`gpt-image-2-4K`	不固定	线路不稳定，可能 503

Grok 模型的 size 参数不可靠，API 返回尺寸不受控。

使用方式

默认服务地址为 http://localhost:8765。

健康检查：

curl http://localhost:8765/health

使用 Grok 绘图：

curl -X POST http://localhost:8765/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cute cat",
    "provider": "grok",
    "size": "1024x1024",
    "n": 1,
    "profile_name": "profile_name"
  }'

使用 GPT 绘图：

curl -X POST http://localhost:8765/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cute cat",
    "provider": "gpt",
    "model": "gpt-image-2-1K",
    "size": "1536x1024",
    "n": 1,
    "profile_name": "profile_name"
  }'

生成结果中的 url 为图片访问地址，例如 http://localhost:8765/output/{profile_name}/{filename}。

调用建议

优先用 Grok：稳定出图，适合日常使用
追求画质用 GPT 1K：请求中设置 "provider": "gpt"
GPT 2K/4K 线路可能不稳定：不推荐作为默认模型
Prompt 用英文：效果通常比中文好
使用 Docker Compose 时，项目的 output/ 会映射到容器的 /app/output

请求参数

请求体为 JSON，发送到 POST /images/generations：

profile_name：必填，调用方 agent 的标识（建议用 agent 名称），不填会报 422 错误；图片会保存到 output/<profile_name>/ 目录
prompt：必填，图片提示词
provider：可选，grok 或 gpt，默认 grok
model：可选，覆盖 provider 的默认模型
size：可选，默认 1024x1024
n：可选，生成数量，范围 1 ~ 10，默认 1

输出规范

图片保存在服务端 output/<profile_name>/ 目录，按调用方 agent 区分
响应返回 filename、url 和文件大小 bytes
图片通过 GET /output/{profile_name}/{filename} 访问
服务启动后，响应中的相对路径 url 需要拼接服务地址，例如 http://localhost:8765/output/{profile_name}/{filename}

Prompt 技巧

基本结构

一个高质量的 prompt 建议包含：主体 + 动作/状态 + 环境 + 光线 + 风格 + 情绪 + 画质后缀。描述越具体，出图越符合预期。

[主体] [动作/状态]，[环境/场景]，[光线]，[风格]，[情绪]，[画质后缀]

示例对比

模糊（效果差）	具体（效果好）
`a cat`	`a fluffy orange tabby cat sleeping on a windowsill, warm afternoon sunlight, cozy living room, photorealistic, peaceful mood, cinematic lighting, highly detailed`
`a car`	`a red sports car driving on a mountain road at sunset, golden hour light, dramatic clouds, cinematic wide shot, sense of speed, 4K, highly detailed`
`a girl`	`a young girl with braided hair reading a book under a cherry blossom tree, soft morning light, anime style, nostalgic mood, detailed illustration`

常用要素清单

光线：golden hour、soft morning light、neon lights、candlelight、cinematic lighting、studio lighting
风格：photorealistic、anime style、watercolor、oil painting、3D render、pixel art、cyberpunk、minimalist
情绪：peaceful、mysterious、energetic、nostalgic、romantic、dark
画质后缀：highly detailed、8K、sharp focus、award winning photography

尺寸参数

size 是请求体里的 JSON 字段，不是命令行参数：

正方形："size": "1024x1024"
横版："size": "1536x1024"（仅 GPT 1K 稳定支持）
Grok 模型的 size 不可靠，输出尺寸不受控，建议固定用 1024x1024

其他建议

使用英文 prompt 效果通常比中文好
需要保持系列风格一致时，把风格描述固定写在 prompt 末尾
想要照片质感：加 photorealistic, cinematic lighting, highly detailed
想要插画/二次元风：指明 anime style, detailed illustration 或 watercolor 等风格词

配置与注意事项

单次上游请求超时为 120 秒
上游请求遇到网络错误或 408/429/500/502/503/504 时，最多自动重试 3 次，并使用指数退避
FastAPI 自动文档地址：http://localhost:8765/docs

5.4 KiB Raw Blame History