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 中显式写「保留原始构图/主体布局」

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本

相关资产