You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
115 lines
3.8 KiB
115 lines
3.8 KiB
---
|
|
name: ai-image
|
|
description: 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/` 目录，并通过 HTTP 返回访问地址。
|
|
|
|
- 服务端 API 不要求调用方提供上游 API Key；上游鉴权通过项目根目录 `.env` 配置
|
|
- `.env` 不应提交到 Git，复制 `.env.example` 为 `.env` 后填写真实 Key
|
|
- 使用 Docker Compose 时会自动读取 `.env` 并注入容器
|
|
|
|
## 可用脚本
|
|
|
|
| 能力 | 服务端文件 | 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/{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 返回尺寸不受控。
|
|
|
|
## 使用方式
|
|
|
|
先启动 FastAPI 服务：
|
|
|
|
```bash
|
|
uvicorn agent-image-t2i:app --host 0.0.0.0 --port 8765
|
|
```
|
|
|
|
默认服务地址为 `http://localhost:8765`。
|
|
|
|
健康检查：
|
|
|
|
```bash
|
|
curl http://localhost:8765/health
|
|
```
|
|
|
|
使用 Grok 绘图：
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8765/images/generations \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"prompt": "a cute cat",
|
|
"provider": "grok",
|
|
"size": "1024x1024",
|
|
"n": 1
|
|
}'
|
|
```
|
|
|
|
使用 GPT 绘图：
|
|
|
|
```bash
|
|
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
|
|
}'
|
|
```
|
|
|
|
生成结果中的 `url` 为图片访问地址，例如 `http://localhost:8765/output/{filename}`。
|
|
|
|
## 调用建议
|
|
|
|
- **优先用 Grok**：稳定出图，适合日常使用
|
|
- **追求画质用 GPT 1K**：请求中设置 `"provider": "gpt"`
|
|
- **GPT 2K/4K 线路可能不稳定**：不推荐作为默认模型
|
|
- **Prompt 用英文**：效果通常比中文好
|
|
- 使用 Docker Compose 时，项目的 `output/` 会映射到容器的 `/app/output`
|
|
|
|
## 请求参数
|
|
|
|
请求体为 JSON，发送到 `POST /images/generations`：
|
|
|
|
- `prompt`：必填，图片提示词
|
|
- `provider`：可选，`grok` 或 `gpt`，默认 `grok`
|
|
- `model`：可选，覆盖 provider 的默认模型
|
|
- `size`：可选，默认 `1024x1024`
|
|
- `n`：可选，生成数量，范围 `1 ~ 10`，默认 `1`
|
|
|
|
## 输出规范
|
|
|
|
- 图片默认保存在服务端 `output/` 目录
|
|
- 响应返回 `filename`、`url` 和文件大小 `bytes`
|
|
- 图片通过 `GET /output/{filename}` 访问
|
|
- 服务启动后，响应中的相对路径 `url` 需要拼接服务地址，例如 `http://localhost:8765/output/{filename}`
|
|
|
|
## Prompt 技巧
|
|
|
|
- 使用英文 prompt 效果更好
|
|
- 描述要具体：主体 + 环境 + 光线 + 风格 + 情绪
|
|
- 横版图用 `--size 1536x1024`，正方形用 `--size 1024x1024`
|
|
- 加上 `cinematic lighting, highly detailed, 4K` 等后缀提升质感
|
|
|
|
## 配置与注意事项
|
|
|
|
- 单次上游请求超时为 120 秒
|
|
- 上游请求遇到网络错误或 408/429/500/502/503/504 时，最多自动重试 3 次，并使用指数退避
|
|
- FastAPI 自动文档地址：`http://localhost:8765/docs`
|
|
|