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.
238 lines
8.9 KiB
238 lines
8.9 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/<profile_name>/` 目录，并通过 HTTP 返回访问地址。
|
|
|
|
## 可用脚本
|
|
|
|
| 能力 | 服务端文件 | HTTP 端点 | 模型 |
|
|
|------|------------|------------|------|
|
|
| GPT / Grok 绘图 | `main.py` | `POST /images/generations` | `gpt-image-2-1K` / `gpt-image-2-2K` / `gpt-image-2-4K` / `grok-imagine-image-lite` |
|
|
| Agnes 绘图（文生图 / 图生图 / 多图合成） | `main.py` | `POST /agnes/images/generations` | `agnes-image-2.1-flash` |
|
|
| 健康检查 | `main.py` | `GET /health` | — |
|
|
| 图片访问 | `main.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`。
|
|
|
|
健康检查：
|
|
|
|
```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,
|
|
"profile_name": "profile_name"
|
|
}'
|
|
```
|
|
|
|
使用 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,
|
|
"profile_name": "profile_name"
|
|
}'
|
|
```
|
|
|
|
生成结果中的 `url` 为图片访问地址，例如 `http://localhost:8765/output/{profile_name}/{filename}`。
|
|
|
|
## Agnes Image 2.1 Flash
|
|
|
|
升级版图像生成模型，针对高信息密度图像和复杂构图做了优化。同时支持**文生图、图生图、多图合成**。
|
|
|
|
### 调用示例
|
|
|
|
文生图（2K, 16:9）：
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8765/agnes/images/generations \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"prompt": "a luminous floating city above a misty canyon at sunrise, cinematic realism",
|
|
"size": "2K",
|
|
"ratio": "16:9",
|
|
"profile_name": "profile_name"
|
|
}'
|
|
```
|
|
|
|
图生图（传入参考图 URL 或 Data URI Base64）：
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8765/agnes/images/generations \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"prompt": "turn the scene into a rainy cyberpunk night while preserving the original composition",
|
|
"size": "1K",
|
|
"ratio": "16:9",
|
|
"images": ["https://example.com/input.png"],
|
|
"profile_name": "profile_name"
|
|
}'
|
|
```
|
|
|
|
多图合成（`images` 传多张）：
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8765/agnes/images/generations \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"prompt": "combine the two characters into an intense fantasy battle scene, dynamic lighting",
|
|
"size": "1K",
|
|
"ratio": "16:9",
|
|
"images": [
|
|
"https://example.com/character-1.png",
|
|
"https://example.com/character-2.png"
|
|
],
|
|
"profile_name": "profile_name"
|
|
}'
|
|
```
|
|
|
|
响应示例：
|
|
|
|
```json
|
|
{
|
|
"model": "agnes-image-2.1-flash",
|
|
"size": "2624x1472",
|
|
"ratio": "16:9",
|
|
"images": [
|
|
{"filename": "agnes-image-2.1-flash-xxxx.png", "url": "/output/profile_name/agnes-image-2.1-flash-xxxx.png", "bytes": 1234567}
|
|
]
|
|
}
|
|
```
|
|
|
|
返回的 `size` 是根据 `size` 档位 + `ratio` 解析出的实际像素尺寸，便于拼接访问地址。
|
|
|
|
### 请求参数
|
|
|
|
请求体为 JSON，发送到 `POST /agnes/images/generations`：
|
|
|
|
- `profile_name`：**必填**，调用方 agent 的标识，图片会保存到 `output/<profile_name>/`
|
|
- `prompt`：必填，文本提示词
|
|
- `size`：可选，尺寸档位 `1K` / `2K` / `3K` / `4K`，或精确尺寸如 `1024x1024`；默认 `1K`
|
|
- `ratio`：可选，宽高比，与 `size` 档位配合使用；支持 `1:1` / `3:4` / `4:3` / `16:9` / `9:16` / `2:3` / `3:2` / `21:9`；默认 `1:1`
|
|
- `images`：可选，图生图或多图合成的输入图像 URL 或 Data URI Base64 列表
|
|
|
|
### 输出尺寸参考
|
|
|
|
| Ratio | 1K | 2K | 3K | 4K |
|
|
|--------|-------------|-------------|-------------|-------------|
|
|
| `1:1` | `1024x1024` | `2048x2048` | `3072x3072` | `4096x4096` |
|
|
| `3:4` | `864x1152` | `1728x2304` | `2592x3456` | `3456x4608` |
|
|
| `4:3` | `1152x864` | `2304x1728` | `3456x2592` | `4608x3456` |
|
|
| `16:9` | `1312x736` | `2624x1472` | `3936x2208` | `5248x2944` |
|
|
| `9:16` | `736x1312` | `1472x2624` | `2208x3936` | `2944x5248` |
|
|
| `2:3` | `832x1248` | `1664x2496` | `2496x3744` | `3328x4992` |
|
|
| `3:2` | `1248x832` | `2496x1664` | `3744x2496` | `4992x3328` |
|
|
| `21:9` | `1568x672` | `3136x1344` | `4704x2016` | `6272x2688` |
|
|
|
|
### 使用注意
|
|
|
|
- 需要服务端配置 `AGNES_API_KEY`（默认走 `https://apihub.agnes-ai.com/v1`，可用 `AGNES_API_BASE_URL` 覆盖）
|
|
- 单次上游请求超时为 360 秒，建议客户端超时 ≥ 60s
|
|
- 上游请求遇到网络错误或 408/429/500/502/503/504 时，最多自动重试 3 次，并使用指数退避
|
|
- 图生图 / 多图合成的参考图必须是可公开访问的 HTTPS URL，否则请用 Data URI Base64
|
|
- 当前定价：免费（`$0 / 张`）
|
|
|
|
## 调用建议
|
|
|
|
- **优先用 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 建议包含：**主体 + 动作/状态 + 环境 + 光线 + 风格 + 情绪 + 画质后缀**。描述越具体，出图越符合预期。
|
|
|
|
```text
|
|
[主体] [动作/状态]，[环境/场景]，[光线]，[风格]，[情绪]，[画质后缀]
|
|
```
|
|
|
|
### 示例对比
|
|
|
|
| 模糊（效果差） | 具体（效果好） |
|
|
|---|---|
|
|
| `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`
|
|
|