toor
/
ai-image
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
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.
12 Commits
1 Branch
0 Tags
450 KiB
 
 
Tag: Branch: Tree: 2598efb5bb
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '2598efb5bb'
${ noResults }
ai-image/SKILL.md

10 KiB
Raw Blame History

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

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
Agnes 上传版（图生图 / 多图合成，multipart） main.py POST /agnes/images/generations/upload agnes-image-2.1-flash
健康检查 main.py GET /health —
图片访问 main.py GET /output/{profile_name}/{filename} —

GPT 模型说明

模型 输出尺寸 备注
gpt-image-2-1K 不固定 线路不稳定，可能 503
gpt-image-2-2K 不固定 线路不稳定，可能 503
gpt-image-2-4K 不固定 线路不稳定，可能 503 
注意, gpt-image-2 画图效果好, 但是有个能出现线路拥堵情况,如果报错,请重试
可以尝试 gpt-image-2-1K, gpt-image-2-2K, gpt-image-2-4K, 三个模型都尝试一下
可以生成 1:1, 4:3, 16:9 的图片

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}。

Agnes Image 2.1 Flash

升级版图像生成模型，针对高信息密度图像和复杂构图做了优化。同时支持文生图、图生图、多图合成。

调用示例

文生图（2K, 16:9）：

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）：

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 传多张）：

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"
  }'

响应示例：

{
  "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 解析出的实际像素尺寸，便于拼接访问地址。

上传版（multipart/form-data）

如果不想手动 base64，可以用 POST /agnes/images/generations/upload，直接传本地图片文件：

单张图：

curl -X POST http://localhost:8765/agnes/images/generations/upload \
  -F "prompt=color this line art with watercolor style, soft palette, preserve composition" \
  -F "profile_name=tester" \
  -F "size=1K" \
  -F "ratio=16:9" \
  -F "images=@/path/to/your-image.png"

多张图（多图合成，images 字段可以传多次）：

curl -X POST http://localhost:8765/agnes/images/generations/upload \
  -F "prompt=combine the two characters into an intense fantasy battle scene" \
  -F "profile_name=tester" \
  -F "size=1K" \
  -F "ratio=16:9" \
  -F "images=@/path/to/character-1.png" \
  -F "images=@/path/to/character-2.png"

Form 字段：

  • prompt：必填，文本提示词
  • profile_name：必填，调用方 agent 的标识
  • size：可选，默认 1K
  • ratio：可选，宽高比；支持 1:1 / 3:4 / 4:3 / 16:9 / 9:16 / 2:3 / 3:2 / 21:9；默认 1:1
  • images：必填，至少上传 1 张，支持 PNG / JPEG / WebP；多张传多个 images 字段即可

响应格式与 JSON 版完全一致。

请求参数

请求体为 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 建议包含：主体 + 动作/状态 + 环境 + 光线 + 风格 + 情绪 + 画质后缀。描述越具体，出图越符合预期。

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

示例对比

模糊（效果差） 具体（效果好）
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