用 Agnes Image 生图踩了 5 个坑，从超时到 Base64 参数全记下来了

用 Agnes Image 2.1 Flash 生成图片，3 张图折腾了一个多小时。不是 API 不好用，是踩了好几个坑才跑通。记下来免得下次再犯。

用的什么服务

Agnes Image 2.1 Flash，Sapiens AI 出的图片生成模型。性价比还可以，$0.003/张。

调用方式就是标准 OpenAI 风格：

POST https://apihub.agnes-ai.com/v1/images/generations
Authorization: Bearer <API_KEY>
Content-Type: application/json

API Key 要自己去拿。去 apihub.agnes-ai.com 注册账号，登录后在 API Keys 页面创建一个 Key。保存到项目根目录的 .env 文件里，格式：

AGNES_API_KEY=sk-xxxxxxxxxxxxxxxx

然后 gen-image.py 会自动读这个文件。

踩的 5 个坑

按时间顺序排。

坑 1：超时时间设太短

Agnes Skill 默认的 Python timeout 是 300 秒，但实际请求在 120-180 秒就触发了 Python 层的 read timed out。每次超时重试又要等 3-5 分钟。

3 次失败，15 分钟白耗。

解决：把 TIMEOUT = 300 改成跟文档推荐的上限对齐，让 Python 层等够时间。

坑 2：提示词太长

这是核心原因。我最开始的提示词写了 400-600 个字符，API 处理慢，频繁触发超时。

Agnes 2.1 Flash 对短提示词响应更快。

解决：压缩到 250-350 字符。删掉冗余的修饰词，只留核心描述。缩短后超时次数明显减少。

# 太长（600 字），容易超时
prompt = "A modern tech illustration of AI agent workflow, showing data processing pipeline with neural network visualization, blue and purple gradient background, minimalist style, high detail, cinematic lighting, 8K quality, professional rendering..."

# 合适（280 字），稳定出图
prompt = "AI agent pipeline diagram, neural network nodes connected by flowing lines, blue purple gradient backdrop, minimalist tech style"

坑 3：分辨率设太高

一上来就跑了 1920×1080，这是最大分辨率，生成耗时最长。

教训：应该先小尺寸测试（1024×576 甚至 640×360），确认 API 正常再换大尺寸。小图跑通了再放大，成本也就多几厘钱。

坑 4：URL 下载失败

API 返回的 data[0].url 用 urllib.request.urlretrieve() 下载时偶尔超时。生图成功了但下载失败，整张图拿不到。

解决：改用 return_base64: true，让 API 直接返回 Base64 字符串，本地解码保存。绕过了 URL 下载环节。

坑 5：Base64 参数放错位置

把 response_format 按常规理解放在了 extra_body 里，结果返回 400。试了几次才确认：return_base64: true 是顶层参数，不是 extra_body 里的。

# 错误：放在 extra_body 里
body = {
    "model": "agnes-image-2.1-flash",
    "prompt": "...",
    "size": "1920x1080",
    "extra_body": {
        "return_base64": true  // 400 Bad Request
    }
}

# 正确：顶层参数
body = {
    "model": "agnes-image-2.1-flash",
    "prompt": "...",
    "size": "1920x1080",
    "return_base64": true  // 正确
}

改对之后，3 张图一次成功，耗时不到 2 分钟。

下次快速出图的 checklist

1. 提示词控制在 250-350 字符
2. 先小尺寸（1024x576）测试，确认 API 正常再跑全量
3. 用 return_base64: true（顶层参数），不放 extra_body
4. Python timeout 至少 300s
5. 失败立即 retry，不要等太久

如果你也用 Agnes API 生过图，评论区聊聊你踩过什么坑。

📄 文档管理系统