agnes-图片生成

原始内容

---
name: agnes-image-gen
description: 使用 Agnes AI 升级版图像生成模型 agnes-image-2.1-flash 生成图片。同时支持文生图（text-to-image）与图生图（image-to-image）。当用户说「用 Agnes 生成图片」「用 Agnes 画一张」「Agnes 生成」「用这张图生成/改成……」或明确要求使用 Agnes API 进行文生图/图生图时，加载本 skill。不消耗 WorkBuddy 积分，仅消耗 Agnes API 额度（当前图像生成免费）。
agent_created: true
---

# Agnes Image Gen

## 概述

调用 Agnes AI 的升级版图像生成模型 **`agnes-image-2.1-flash`**（Sapiens AI 出品）。该模型同时支持：

- **文生图（Text-to-Image）**：根据文本提示词生成全新图像
- **图生图（Image-to-Image）**：基于输入图像进行转换、重绘、风格化编辑，并尽量保留原始构图

通过 curl 直接调用 HTTP API，不走 WorkBuddy 的对话模型机制，因此**不消耗对话积分**。当前图像生成定价为 **$0 / 张**。

## 触发条件

当用户提出以下请求时加载本 skill：
- 「用 Agnes 生成一张……的图片」
- 「用 Agnes 画……」
- 「Agnes 图片生成」
- 「用这张图片生成……」「把这张图片改成……风格」「给这张图换个背景」（图生图）
- 明确要求使用 Agnes API 进行文生图或图生图

## 核心能力

- **高信息密度图像**：适合复杂场景、丰富构图、多层视觉元素（精细场景、复杂环境、丰富构图）
- **构图保留**：图生图编辑时尽量保留原始构图与主体布局
- **灵活尺寸控制**：使用 `1K` / `2K` / `3K` / `4K` 档位，配合宽高比
- **URL / Base64 输出**：支持图像 URL 或 Base64 数据返回
- **适用场景**：创意设计、营销内容、产品可视化、社交媒体素材、图像转换（风格迁移 / 场景重打光 / 背景变换）

## API Reference

### Endpoint（双端点容灾）

脚本自动按以下顺序尝试，前一个访问不了就切到下一个，**无需手动干预**：

| 优先级 | Endpoint | 说明 |
|--------|----------|------|
| 1（主） | `https://apihub.agnes-ai.com/v1/images/generations` | 国际主端点 |
| 2（容灾） | `https://apihub.agnes-ai.cn/v1/images/generations` | **国内容灾端点**：主端点 TCP 不可达时自动切换（国内网络访问 Agnes 更稳） |

- 调用前会做轻量连通性探测（TCP 层，8s 超时），主端点不可达时**立即跳过**而非空等，再尝试国内网关。
- 端点可达但请求失败（限速/5xx）会在该端点内重试，耗尽后才跳到下一端点。
- 运行结束会打印「本次使用: <实际端点>」，方便确认走的是哪个。

> 注意：文生图与图生图**共用同一端点** `/v1/images/generations`，不再使用 `/v1/images/edits`。

### 请求头

```
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 模型名称，固定为 `agnes-image-2.1-flash` |
| `prompt` | string | 是 | 图像生成或图像编辑的文本指令 |
| `size` | string | 是 | 输出尺寸档位，推荐 `1K` / `2K` / `3K` / `4K`；兼容 `1024x768` 这类历史精确写法（不支持的尺寸可能被标准化） |
| `ratio` | string | 否 | 与档位式 `size` 配合的宽高比，支持 `1:1`、`3:4`、`4:3`、`16:9`、`9:16`、`2:3`、`3:2`、`21:9`，默认 `1:1` |
| `image` | string[] | 图生图必填 | 输入图像数组（**注意：放在 `extra_body.image` 中**，见下方图生图示例） |
| `return_base64` | boolean | 否 | 文生图需要以 Base64 返回时设为 `true` |
| `extra_body` | object | 否 | 高级工作流附加参数（见下） |
| `extra_body.response_format` | string | 否 | 输出格式：`url` 或 `b64_json` |
| `extra_body.image` | string[] | 图生图必填 | 输入图像数组，支持公共图像 URL 或 `data:image/...;base64,...` Data URI |

### 尺寸与宽高比（输出尺寸参考）

为获得可预期的输出尺寸，建议将 `size` 与 `ratio` 配合使用：

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

> 若请求 `1920x1080` / `2560x1440` 这类非原生精确尺寸，服务会自动映射到最接近的档位与宽高比（如 16:9 的 `1K` 输出为 `1312x736`）。需要标准显示器素材时建议请求 `size:"2K"` + `ratio:"16:9"`，再下游裁剪。

## 工作流程

### 1. 文生图（Text-to-Image）

```bash
curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "<用户描述的图片内容>",
    "size": "2K",
    "ratio": "1:1",
    "extra_body": {
      "response_format": "url"
    }
  }'
```

- `size` 支持档位式（`1K`/`2K`/`3K`/`4K`）或兼容精确写法（`1024x1024` 等）
- 需要 Base64 时把 `extra_body.response_format` 改为 `b64_json`，或用顶层 `return_base64: true`

### 2. 图生图（Image-to-Image）

图生图**同样调用 `/v1/images/generations`**，输入图像通过 `extra_body.image` 传入（数组，支持 URL 或 Data URI）：

```bash
curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "将白天街道场景改为电影级赛博朋克夜景，添加霓虹招牌和湿滑路面倒影，保留原始街道布局与建筑形状",
    "size": "2K",
    "extra_body": {
      "image": ["https://example.com/input-image.png"],
      "response_format": "url"
    }
  }'
```

- 输入图像为数组，可放多个（多图合成），每个元素为公共 HTTPS URL 或 `data:image/png;base64,...`
- 输入图像 URL 必须可公开访问（无需登录/cookie）；不可公开时改用 Data URI Base64
- **不需要**传递 `tags: ["img2img"]`

### 3. 响应处理

URL 输出：
```json
{
  "created": 1780000000,
  "data": [{
    "url": "https://storage.googleapis.com/agnes-aigc/xxx.png",
    "b64_json": null,
    "revised_prompt": null
  }]
}
```

Base64 输出：
```json
{
  "created": 1780000000,
  "data": [{
    "url": null,
    "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
    "revised_prompt": null
  }]
}
```

- URL 输出：从 `data[0].url` 提取
- Base64 输出：从 `data[0].b64_json` 解码保存

### 4. 下载图片到本地

**URL 输出**（PowerShell）：
```powershell
Invoke-WebRequest -Uri "<图片URL>" -OutFile "<保存路径>/agnes_output.png"
```

**URL 输出**（Python，跨平台，带时间戳）：
```python
import urllib.request, os
from datetime import datetime
url = "<图片URL>"
ts = datetime.now().strftime("%Y%m%d_%H%M%S")
save_path = os.path.join("<workspace路径>", f"agnes_{ts}.png")
urllib.request.urlretrieve(url, save_path)
```

**Base64 输出**（Python）：
```python
import base64, os
from datetime import datetime
b64 = "<data[0].b64_json>"
ts = datetime.now().strftime("%Y%m%d_%H%M%S")
save_path = os.path.join("<workspace路径>", f"agnes_{ts}.png")
with open(save_path, "wb") as f:
    f.write(base64.b64decode(b64))
```

> 图片 URL 来自 Google Cloud Storage，有访问时效，应尽快下载到本地。若下载失败，可改用 HTML 页面直接引用远程 URL（`<img>` 加载）再叠加 CSS 文字制成海报。

### 5. 展示给用户

- 调用 `preview_url` 展示图片文件
- 调用 `deliver_attachments` 交付图片附件

## 调用示例

### 示例 1：软件宣传海报（文生图，档位+宽高比）

**用户请求**：「用 Agnes 生成一张科技感产品发布会海报，主题 AI 助手」

```bash
curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "科技感产品发布会海报，主题是AI助手，未来主义风格，蓝色调，holographic效果，现代简约设计",
    "size": "2K",
    "ratio": "1:1",
    "extra_body": { "response_format": "url" }
  }'
```

### 示例 2：多张不同风格（文生图，n 参数）

```bash
curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "咖啡店logo设计，简约现代风格，咖啡杯元素，温暖色调",
    "size": "1K",
    "extra_body": { "response_format": "url" }
  }'
```

> 需要多张时，部分场景可用 `n` 参数（旧写法）；当前档位式请求建议单张循环获取多种方案。

### 示例 3：图片风格转换（图生图，URL 输入）

**用户请求**：「把这张照片改成赛博朋克风格」

```bash
curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "转换为赛博朋克风格，霓虹灯光效，未来科技感，暗色调，高对比度，保留原构图",
    "size": "2K",
    "extra_body": {
      "image": ["https://example.com/photo.jpg"],
      "response_format": "url"
    }
  }'
```

### 示例 4：图片元素修改（图生图，Base64 Data URI 输入）

**用户请求**：「把图片中的天空改成星空」

```bash
curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "将天空替换为璀璨星空，银河清晰可见，深蓝色调，保留原主体与构图",
    "size": "2K",
    "extra_body": {
      "image": ["data:image/png;base64,<BASE64_HERE>"],
      "response_format": "b64_json"
    }
  }'
```

### 示例 5：中文文本优化示例（含中文字样）

**用户请求**：「生成一张带『新年快乐』字样的贺卡」

**优化后的 prompt**：
```
精美新年贺卡设计，主视觉为"新年快乐"艺术字体，金色书法风格，红色背景，烟花装饰，喜庆氛围，中国传统元素，高清精致
```

```bash
curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "精美新年贺卡设计，主视觉为'新年快乐'艺术字体，金色书法风格，红色背景，烟花装饰，喜庆氛围，中国传统元素，高清精致",
    "size": "1K",
    "extra_body": { "response_format": "url" }
  }'
```

## 中文文本生成优化

### 官方推荐提示词结构

**文生图**：`[主体] + [场景/环境] + [风格] + [光照] + [构图] + [质量要求]`
```
日出时分薄雾峡谷上方的发光浮空城市，电影级写实风格，广角构图，丰富的建筑细节，柔和的金色光线，高视觉密度
```

**图生图**：`[改变要求] + [新风格/场景] + [添加或移除的元素] + [需要保留的元素]`
```
将白天街道场景改为电影级赛博朋克夜景，添加霓虹招牌和湿滑路面倒影，同时保留原始街道布局、相机角度和主要建筑形状。
```

**高信息密度图像**：清晰描述视觉层次结构（主要主体、背景环境、重要次要细节、风格、光照、构图约束）
```
建在悬崖上的大型奇幻港口城市，数百艘小船，层叠的石桥，发光的窗户，远山，多云的日落天空，电影级奇幻写实风格，广角构图，丰富的建筑细节，高视觉密度
```

### 最佳实践

1. **详细描述**：风格、颜色、氛围、元素、光照、构图尽量写全
2. **关键词组合**：逗号分隔多个关键词，如「科技感, 蓝色调, 未来主义, 简约设计」
3. **风格指定**：明确风格名称，如「水彩画风格」「像素艺术」「3D渲染」「电影级写实」
4. **质量修饰词**：「高清」「精致」「专业级」「高视觉密度」
5. **构图指导**：「居中构图」「对称设计」「留白艺术」「广角构图」
6. **尺寸策略**：标准方图用 `size:"1K"`+`ratio:"1:1"`；横幅/封面用 `size:"2K"`+`ratio:"16:9"`；手机壁纸用 `9:16`

### 常见问题解决

- **中文字符显示不清晰**：prompt 中强调「清晰中文字体」「可读性」「高对比度」
- **图片不符合预期**：使用更具体描述，避免模糊词汇，加「精确」「准确」
- **需要特定风格**：明确风格名称，如「中国风水彩」「日系动漫」「欧美卡通」
- **需要精确显示器分辨率**（如 1920x1080）：用 `size:"2K"`+`ratio:"16:9"`，下游裁剪

## 错误与故障排除

### 常见错误

| 错误 | 原因 | 解决 |
|------|------|------|
| `model_not_found` | 模型名错误 | 确认使用 `agnes-image-2.1-flash` |
| `rate_limit_exceeded` | 调用频率过高 | 等待后重试，降低并发 |
| `invalid_image_format` | 图片格式/编码错误 | 确保 JPEG/PNG，Base64 编码正确 |
| `prompt_too_long` | 提示词过长 | 精简，保留关键描述 |
| 请求超时 | 生成耗时数秒到数十秒 | 客户端超时设为 `60s-360s` |
| 输入图像 URL 无法访问 | 私有/需登录 | 改用 Data URI Base64 |

### 高频坑（官方强调）

1. **不要顶层放 `response_format`**：应放在 `extra_body.response_format`
   - ❌ `{"model":..., "response_format": "url"}`
   - ✅ `{"model":..., "extra_body": {"response_format": "url"}}`
2. **图生图不要传 `tags: ["img2img"]`**：只需在 `extra_body.image` 提供输入图像
3. **图生图缺少 image**：`extra_body.image` 为必填数组
4. **文生图三必填**：`model` + `prompt` + `size`

### 错误响应格式

```json
{
  "error": {
    "message": "错误描述",
    "type": "错误类型",
    "code": "错误代码"
  }
}
```

## 注意事项

- API Key 已在请求中硬编码，无需用户额外提供（如需自定义，替换 `Authorization` 中的 Bearer 值）
- 图片 URL 来自 Google Cloud Storage，有访问时效，应尽快下载到本地
- 若 API 返回错误，如实报告给用户，不做猜测
- 中文 prompt 已优化，可直接用中文描述，效果良好
- 图生图统一走 `/v1/images/generations`，输入图像放 `extra_body.image`
- 生成的图片可能含 AI 伪影，必要时可后期处理
- 标准价格 `$0.003/张`，**当前免费 `$0/张`**

## 最佳实践

1. **明确需求**：调用前明确文生图还是图生图
2. **优化 Prompt**：用详细、具体描述，遵循官方提示词结构
3. **选尺寸档位**：用 `1K/2K/3K/4K` + `ratio` 获得可预期输出
4. **及时保存**：生成后立即下载，避免 URL 过期
5. **错误重试**：按错误类型对应处理；超时调大客户端超时时间
6. **图生图保留构图**：prompt 中显式写「保留原始构图/主体布局」

name: agnes-image-gen description: 使用 Agnes AI 升级版图像生成模型 agnes-image-2.1-flash 生成图片。同时支持文生图（text-to-image）与图生图（image-to-image）。当用户说「用 Agnes 生成图片」「用 Agnes 画一张」「Agnes 生成」「用这张图生成/改成……」或明确要求使用 Agnes API 进行文生图/图生图时，加载本 skill。不消耗 WorkBuddy 积分，仅消耗 Agnes API 额度（当前图像生成免费）。 agent_created: true

Agnes Image Gen

概述

调用 Agnes AI 的升级版图像生成模型 agnes-image-2.1-flash（Sapiens AI 出品）。该模型同时支持：

文生图（Text-to-Image）：根据文本提示词生成全新图像
图生图（Image-to-Image）：基于输入图像进行转换、重绘、风格化编辑，并尽量保留原始构图

通过 curl 直接调用 HTTP API，不走 WorkBuddy 的对话模型机制，因此不消耗对话积分。当前图像生成定价为 $0 / 张。

触发条件

当用户提出以下请求时加载本 skill：

「用 Agnes 生成一张……的图片」
「用 Agnes 画……」
「Agnes 图片生成」
「用这张图片生成……」「把这张图片改成……风格」「给这张图换个背景」（图生图）
明确要求使用 Agnes API 进行文生图或图生图

核心能力

高信息密度图像：适合复杂场景、丰富构图、多层视觉元素（精细场景、复杂环境、丰富构图）
构图保留：图生图编辑时尽量保留原始构图与主体布局
灵活尺寸控制：使用 1K / 2K / 3K / 4K 档位，配合宽高比
URL / Base64 输出：支持图像 URL 或 Base64 数据返回
适用场景：创意设计、营销内容、产品可视化、社交媒体素材、图像转换（风格迁移 / 场景重打光 / 背景变换）

API Reference

Endpoint（双端点容灾）

脚本自动按以下顺序尝试，前一个访问不了就切到下一个，无需手动干预：

优先级	Endpoint	说明
1（主）	`https://apihub.agnes-ai.com/v1/images/generations`	国际主端点
2（容灾）	`https://apihub.agnes-ai.cn/v1/images/generations`	国内容灾端点：主端点 TCP 不可达时自动切换（国内网络访问 Agnes 更稳）

调用前会做轻量连通性探测（TCP 层，8s 超时），主端点不可达时立即跳过而非空等，再尝试国内网关。
端点可达但请求失败（限速/5xx）会在该端点内重试，耗尽后才跳到下一端点。
运行结束会打印「本次使用: <实际端点>」，方便确认走的是哪个。

注意：文生图与图生图共用同一端点 /v1/images/generations，不再使用 /v1/images/edits。

请求头

-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，固定为 `agnes-image-2.1-flash`
`prompt`	string	是	图像生成或图像编辑的文本指令
`size`	string	是	输出尺寸档位，推荐 `1K` / `2K` / `3K` / `4K`；兼容 `1024x768` 这类历史精确写法（不支持的尺寸可能被标准化）
`ratio`	string	否	与档位式 `size` 配合的宽高比，支持 `1:1`、`3:4`、`4:3`、`16:9`、`9:16`、`2:3`、`3:2`、`21:9`，默认 `1:1`
`image`	string[]	图生图必填	输入图像数组（注意：放在 `extra_body.image` 中，见下方图生图示例）
`return_base64`	boolean	否	文生图需要以 Base64 返回时设为 `true`
`extra_body`	object	否	高级工作流附加参数（见下）
`extra_body.response_format`	string	否	输出格式：`url` 或 `b64_json`
`extra_body.image`	string[]	图生图必填	输入图像数组，支持公共图像 URL 或 `data:image/...;base64,...` Data URI

尺寸与宽高比（输出尺寸参考）

为获得可预期的输出尺寸，建议将 size 与 ratio 配合使用：

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

若请求 1920x1080 / 2560x1440 这类非原生精确尺寸，服务会自动映射到最接近的档位与宽高比（如 16:9 的 1K 输出为 1312x736）。需要标准显示器素材时建议请求 size:"2K" + ratio:"16:9"，再下游裁剪。

工作流程

1. 文生图（Text-to-Image）

curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "<用户描述的图片内容>",
    "size": "2K",
    "ratio": "1:1",
    "extra_body": {
      "response_format": "url"
    }
  }'

size 支持档位式（1K/2K/3K/4K）或兼容精确写法（1024x1024 等）
需要 Base64 时把 extra_body.response_format 改为 b64_json，或用顶层 return_base64: true

2. 图生图（Image-to-Image）

图生图同样调用 /v1/images/generations，输入图像通过 extra_body.image 传入（数组，支持 URL 或 Data URI）：

curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "将白天街道场景改为电影级赛博朋克夜景，添加霓虹招牌和湿滑路面倒影，保留原始街道布局与建筑形状",
    "size": "2K",
    "extra_body": {
      "image": ["https://example.com/input-image.png"],
      "response_format": "url"
    }
  }'

输入图像为数组，可放多个（多图合成），每个元素为公共 HTTPS URL 或 data:image/png;base64,...
输入图像 URL 必须可公开访问（无需登录/cookie）；不可公开时改用 Data URI Base64
不需要传递 tags: ["img2img"]

3. 响应处理

URL 输出：

{
  "created": 1780000000,
  "data": [{
    "url": "https://storage.googleapis.com/agnes-aigc/xxx.png",
    "b64_json": null,
    "revised_prompt": null
  }]
}

Base64 输出：

{
  "created": 1780000000,
  "data": [{
    "url": null,
    "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
    "revised_prompt": null
  }]
}

URL 输出：从 data[0].url 提取
Base64 输出：从 data[0].b64_json 解码保存

4. 下载图片到本地

URL 输出（PowerShell）：

Invoke-WebRequest -Uri "<图片URL>" -OutFile "<保存路径>/agnes_output.png"

URL 输出（Python，跨平台，带时间戳）：

import urllib.request, os
from datetime import datetime
url = "<图片URL>"
ts = datetime.now().strftime("%Y%m%d_%H%M%S")
save_path = os.path.join("<workspace路径>", f"agnes_{ts}.png")
urllib.request.urlretrieve(url, save_path)

Base64 输出（Python）：

import base64, os
from datetime import datetime
b64 = "<data[0].b64_json>"
ts = datetime.now().strftime("%Y%m%d_%H%M%S")
save_path = os.path.join("<workspace路径>", f"agnes_{ts}.png")
with open(save_path, "wb") as f:
    f.write(base64.b64decode(b64))

图片 URL 来自 Google Cloud Storage，有访问时效，应尽快下载到本地。若下载失败，可改用 HTML 页面直接引用远程 URL（<img> 加载）再叠加 CSS 文字制成海报。

5. 展示给用户

调用 preview_url 展示图片文件
调用 deliver_attachments 交付图片附件

调用示例

示例 1：软件宣传海报（文生图，档位+宽高比）

用户请求：「用 Agnes 生成一张科技感产品发布会海报，主题 AI 助手」

curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "科技感产品发布会海报，主题是AI助手，未来主义风格，蓝色调，holographic效果，现代简约设计",
    "size": "2K",
    "ratio": "1:1",
    "extra_body": { "response_format": "url" }
  }'

示例 2：多张不同风格（文生图，n 参数）

curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "咖啡店logo设计，简约现代风格，咖啡杯元素，温暖色调",
    "size": "1K",
    "extra_body": { "response_format": "url" }
  }'

需要多张时，部分场景可用 n 参数（旧写法）；当前档位式请求建议单张循环获取多种方案。

示例 3：图片风格转换（图生图，URL 输入）

用户请求：「把这张照片改成赛博朋克风格」

curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "转换为赛博朋克风格，霓虹灯光效，未来科技感，暗色调，高对比度，保留原构图",
    "size": "2K",
    "extra_body": {
      "image": ["https://example.com/photo.jpg"],
      "response_format": "url"
    }
  }'

示例 4：图片元素修改（图生图，Base64 Data URI 输入）

用户请求：「把图片中的天空改成星空」

curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "将天空替换为璀璨星空，银河清晰可见，深蓝色调，保留原主体与构图",
    "size": "2K",
    "extra_body": {
      "image": ["data:image/png;base64,<BASE64_HERE>"],
      "response_format": "b64_json"
    }
  }'

示例 5：中文文本优化示例（含中文字样）

用户请求：「生成一张带『新年快乐』字样的贺卡」

优化后的 prompt：

精美新年贺卡设计，主视觉为"新年快乐"艺术字体，金色书法风格，红色背景，烟花装饰，喜庆氛围，中国传统元素，高清精致

curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-8Rzd2yCbFzOi1vxojseH8C5D8w3u4aMdNWsPNzxk0G7339Cz" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "精美新年贺卡设计，主视觉为'新年快乐'艺术字体，金色书法风格，红色背景，烟花装饰，喜庆氛围，中国传统元素，高清精致",
    "size": "1K",
    "extra_body": { "response_format": "url" }
  }'

中文文本生成优化

官方推荐提示词结构

文生图：[主体] + [场景/环境] + [风格] + [光照] + [构图] + [质量要求]

日出时分薄雾峡谷上方的发光浮空城市，电影级写实风格，广角构图，丰富的建筑细节，柔和的金色光线，高视觉密度

图生图：[改变要求] + [新风格/场景] + [添加或移除的元素] + [需要保留的元素]

将白天街道场景改为电影级赛博朋克夜景，添加霓虹招牌和湿滑路面倒影，同时保留原始街道布局、相机角度和主要建筑形状。

高信息密度图像：清晰描述视觉层次结构（主要主体、背景环境、重要次要细节、风格、光照、构图约束）

建在悬崖上的大型奇幻港口城市，数百艘小船，层叠的石桥，发光的窗户，远山，多云的日落天空，电影级奇幻写实风格，广角构图，丰富的建筑细节，高视觉密度

最佳实践

详细描述：风格、颜色、氛围、元素、光照、构图尽量写全
关键词组合：逗号分隔多个关键词，如「科技感, 蓝色调, 未来主义, 简约设计」
风格指定：明确风格名称，如「水彩画风格」「像素艺术」「3D渲染」「电影级写实」
质量修饰词：「高清」「精致」「专业级」「高视觉密度」
构图指导：「居中构图」「对称设计」「留白艺术」「广角构图」
尺寸策略：标准方图用 size:"1K"+ratio:"1:1"；横幅/封面用 size:"2K"+ratio:"16:9"；手机壁纸用 9:16

常见问题解决

中文字符显示不清晰：prompt 中强调「清晰中文字体」「可读性」「高对比度」
图片不符合预期：使用更具体描述，避免模糊词汇，加「精确」「准确」
需要特定风格：明确风格名称，如「中国风水彩」「日系动漫」「欧美卡通」
需要精确显示器分辨率（如 1920x1080）：用 size:"2K"+ratio:"16:9"，下游裁剪

错误与故障排除

常见错误

错误	原因	解决
`model_not_found`	模型名错误	确认使用 `agnes-image-2.1-flash`
`rate_limit_exceeded`	调用频率过高	等待后重试，降低并发
`invalid_image_format`	图片格式/编码错误	确保 JPEG/PNG，Base64 编码正确
`prompt_too_long`	提示词过长	精简，保留关键描述
请求超时	生成耗时数秒到数十秒	客户端超时设为 `60s-360s`
输入图像 URL 无法访问	私有/需登录	改用 Data URI Base64

高频坑（官方强调）

不要顶层放 response_format：应放在 extra_body.response_format
- ❌ {"model":..., "response_format": "url"}
- ✅ {"model":..., "extra_body": {"response_format": "url"}}
图生图不要传 tags: ["img2img"]：只需在 extra_body.image 提供输入图像
图生图缺少 image：extra_body.image 为必填数组
文生图三必填：model + prompt + size

错误响应格式

{
  "error": {
    "message": "错误描述",
    "type": "错误类型",
    "code": "错误代码"
  }
}

注意事项

API Key 已在请求中硬编码，无需用户额外提供（如需自定义，替换 Authorization 中的 Bearer 值）
图片 URL 来自 Google Cloud Storage，有访问时效，应尽快下载到本地
若 API 返回错误，如实报告给用户，不做猜测
中文 prompt 已优化，可直接用中文描述，效果良好
图生图统一走 /v1/images/generations，输入图像放 extra_body.image
生成的图片可能含 AI 伪影，必要时可后期处理
标准价格 $0.003/张，当前免费 $0/张

最佳实践

明确需求：调用前明确文生图还是图生图
优化 Prompt：用详细、具体描述，遵循官方提示词结构
选尺寸档位：用 1K/2K/3K/4K + ratio 获得可预期输出
及时保存：生成后立即下载，避免 URL 过期
错误重试：按错误类型对应处理；超时调大客户端超时时间
图生图保留构图：prompt 中显式写「保留原始构图/主体布局」