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

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

用 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 字符。删掉冗余的修饰词，只留核心描述。缩短后超时次数明显减少。

```python
# 太长（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` 里的。

```python
# 错误：放在 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 生过图，评论区聊聊你踩过什么坑。

摘要

标签多个标签用逗号分隔

分类