--- name: agnes-image description: 使用 Agnes AI（OpenAI 兼容网关）生成与理解图片、生成视频。支持文生图、图生图（保持角色一致性）、贴纸/卡通形象生成、白底转透明 PNG、多模态图片理解（描述/分析/问答/OCR），以及文生视频、图生视频、多图视频、关键帧动画。 category: Creative Generation --- # Agnes Image 本 Skill 封装了 Agnes AI 的图像生成能力（模型 `agnes-image-2.1-flash`），接口兼容 OpenAI 风格，支持文生图、图生图，并内置「白底转透明」后处理，适合批量生成游戏/应用所需的角色、图标、贴纸等素材。 ## 前置条件 设置 API Key（二选一）： ```bash export AGNES_API_KEY="sk-xxxxxxxx" ``` 或在每次调用时通过 `--api-key` 传入。 ## 使用方法 ### 文生图 生成单张图片，输出可访问的图片链接： ```bash python {baseDir}/scripts/generate_image.py --prompt "一只圆润萌系的小火龙，大眼睛，贴纸风格" ``` 指定尺寸（宽高**必须是 16 的倍数**，如 `1024x768`、`1152x768`）： ```bash python {baseDir}/scripts/generate_image.py --prompt "壮丽的山川日出" --size "1024x768" ``` > ⚠️ 生成图片的宽和高都必须是 16 的倍数。脚本会自动把传入的尺寸四舍五入到最近的 16 倍数，并在 stderr 提示调整结果。 ### 图生图（保持一致性） 提供参考图 URL 或 `data:image` Base64，让新图沿用参考图的角色/构图： ```bash python {baseDir}/scripts/generate_image.py \ --prompt "把这只小龙变成展翅的成年形态，保持配色和脸部不变" \ --image "https://example.com/baby-dragon.png" ``` 可多次指定 `--image` 传入多张参考图。 ### 下载保存到本地 加 `--save`，脚本会下载图片并保存，输出 `SAVED:`： ```bash python {baseDir}/scripts/generate_image.py --prompt "一只小猫贴纸" --save ./outputs/cat.png ``` ### 白底转透明 PNG 配合 `--save --transparent`，自动把纯白背景抠成透明（保留主体内部白色，如白描边、白肚皮）： ```bash python {baseDir}/scripts/generate_image.py \ --prompt "一只圆润萌系企鹅，白色背景，贴纸风格" \ --save ./outputs/penguin.png --transparent ``` 边缘若有白色残留，可调高容差 `--thresh`（默认 60）。 ## 参数说明 - `--prompt`: (必选) 图像生成的文本描述，支持中英文。 - `--model`: (可选) 模型 ID，默认 `agnes-image-2.1-flash`。 - `--size`: (可选) 图像尺寸，如 `1024x1024`、`1024x768`，默认 `1024x1024`。**宽高必须是 16 的倍数**，否则脚本会自动规整到最近的 16 倍数。 - `--image`: (可选) 参考图 URL 或 `data:image/...;base64,...`，用于图生图，可多次指定。 - `--api-key`: (可选) Agnes API Key，未提供时读取 `AGNES_API_KEY` 环境变量。 - `--save`: (可选) 下载并保存到指定本地路径。 - `--transparent`: (可选) 配合 `--save`，把纯白背景转为透明 PNG（需 Pillow）。 - `--thresh`: (可选) 透明化时的白色容差，默认 60，值越大清除越彻底。 ## 工作流 1. 调用 `generate_image.py` 脚本。 2. 脚本始终输出以 `MEDIA_URL: ` 开头的图片链接，用 Markdown 展示：`![image](URL)`。 3. 加了 `--save` 时，会额外下载到本地并输出以 `SAVED: ` 开头的文件路径（`MEDIA_URL` 仍会一并输出）。 4. 生成的图片链接来自 Agnes 平台输出存储，可直接公网访问。 > 注：`--save --transparent` 时，`MEDIA_URL` 指向 Agnes 返回的原始白底图，本地 `SAVED` 文件才是抠好的透明 PNG。 ## 批量生成小贴士 生成系列素材（如角色的多个进化阶段）时，建议： - 在每个 prompt 中固定统一的「风格描述」（如 `chibi kawaii sticker, big eyes, white background`），保证视觉一致。 - 需要严格保持同一角色时，用 `--image` 把上一阶段的图当参考做图生图。 - 透明素材直接用 `--save --transparent`，省去手动抠图。 ## 注意事项 - 接口兼容 OpenAI 风格，Base URL 为 `https://apihub.agnes-ai.com/v1`。 - API Key 属于敏感信息，请勿提交到公开仓库或硬编码到代码中。 - 图生图时，确保参考图 URL 可公开访问。 - 透明化基于「边缘漫水填充」，仅对纯色（白）背景效果最佳；复杂背景请勿使用 `--transparent`。 --- ## 图片理解（多模态） 使用 `understand_image.py` 让模型（默认 `agnes-2.0-flash`）基于图片进行描述、分析、问答或信息提取。支持公网图片 URL，也支持本地图片文件（自动转 Base64）。 ### 理解图片 URL ```bash python {baseDir}/scripts/understand_image.py \ --prompt "用中文描述这张图片的内容和风格" \ --image "https://example.com/image.jpg" ``` ### 理解本地图片 ```bash python {baseDir}/scripts/understand_image.py \ --prompt "这是什么动物？什么颜色？" \ --image-file ./outputs/fox.png ``` ### 多图对比 / 信息提取 可多次指定 `--image` 或 `--image-file` 传入多张图片： ```bash python {baseDir}/scripts/understand_image.py \ --prompt "比较这两张图的差异" \ --image-file ./a.png --image-file ./b.png ``` ### 带系统提示 ```bash python {baseDir}/scripts/understand_image.py \ --prompt "提取图中所有文字" \ --image "https://example.com/poster.jpg" \ --system "你是专业的 OCR 助手，只输出图中文字" ``` ### 图片理解参数说明 - `--prompt`: (必选) 对图片的问题或指令。 - `--image`: (可选) 图片公网 URL 或 `data:image` Base64，可多次指定。 - `--image-file`: (可选) 本地图片文件路径，自动转 Base64，可多次指定。 - `--system`: (可选) 系统提示（system 消息）。 - `--model`: (可选) 模型 ID，默认 `agnes-2.0-flash`。 - `--temperature`: (可选) 采样温度，越低越确定。 - `--max-tokens`: (可选) 最多生成的 token 数。 - `--api-key`: (可选) Agnes API Key，未提供时读取 `AGNES_API_KEY` 环境变量。 ### 图片理解工作流 1. 调用 `understand_image.py` 脚本。 2. 脚本直接输出模型的文本回答（无前缀），可直接读取使用。 3. 不传任何图片时，会退化为普通文本对话。 --- ## 视频生成（异步） 使用 `generate_video.py` 生成视频（模型 `agnes-video-v2.0`）。视频生成是异步任务，脚本会自动创建任务并轮询，完成后输出视频链接。生成通常需要 1-3 分钟。 > ⚠️ **重要：视频生成用到的所有参考图（图生视频 / 多图 / 关键帧）必须是「可公网访问的图片 URL」**（`http://` 或 `https://`），**不支持本地文件路径，也不支持 Base64**。 > 如果你手上只有本地图片，请先： > 1. 用 `generate_image.py` 生成图片，它返回的 `MEDIA_URL` 就是可直接使用的公网 URL；或 > 2. 把本地图片上传到图床 / 对象存储（如 S3、R2）后，使用其公网 URL。 > > 脚本会校验 `--image` 是否为合法 URL，传入本地路径会直接报错并给出提示。 ### 文生视频 ```bash python {baseDir}/scripts/generate_video.py \ --prompt "A cinematic shot of a cat walking on the beach at sunset, warm golden lighting" \ --duration 5 ``` ### 图生视频（让单张图动起来） ```bash python {baseDir}/scripts/generate_video.py \ --prompt "The character breathes gently, hair moving in the wind, keep face consistent" \ --image "https://example.com/character.png" --duration 5 ``` ### 多图视频（在多张图之间过渡） ```bash python {baseDir}/scripts/generate_video.py \ --prompt "Smooth transformation between the two scenes, cinematic pacing" \ --image "https://example.com/a.png" --image "https://example.com/b.png" ``` ### 关键帧动画 ```bash python {baseDir}/scripts/generate_video.py \ --prompt "Smooth transition between keyframes, maintain character identity" \ --image "https://example.com/k1.png" --image "https://example.com/k2.png" \ --keyframes ``` ### 下载保存 ```bash python {baseDir}/scripts/generate_video.py --prompt "日出延时摄影" --duration 5 --save ./out.mp4 ``` ### 视频参数说明 - `--prompt`: (必选) 视频内容的文本描述。 - `--model`: (可选) 模型 ID，默认 `agnes-video-v2.0`。 - `--image`: (可选) 参考图 URL；1 张=图生视频，2 张及以上=多图视频，可多次指定。 - `--keyframes`: (可选) 关键帧动画模式（配合多张 `--image`）。 - `--duration`: (可选) 目标时长(秒)，按帧率自动换算帧数（覆盖 `--num-frames`）。 - `--num-frames`: (可选) 帧数，必须 ≤441 且满足 8n+1，默认 121（约 5 秒）；脚本会自动规整。 - `--frame-rate`: (可选) 帧率 1-60，默认 24。 - `--width` / `--height`: (可选) 分辨率，默认 1152×768；服务端会标准化到最接近的档位。 - `--negative-prompt`: (可选) 负向提示词。 - `--seed`: (可选) 随机种子，用于结果复现。 - `--save`: (可选) 下载视频并保存到本地。 - `--poll-interval`: (可选) 轮询间隔秒数，默认 5。 - `--max-wait`: (可选) 最大等待秒数，默认 600。 - `--api-key`: (可选) Agnes API Key，未提供时读取 `AGNES_API_KEY` 环境变量。 ### 常用时长参数 | 目标时长 | 推荐参数 | |---------|---------| | 约 3 秒 | `--num-frames 81 --frame-rate 24` | | 约 5 秒 | `--num-frames 121 --frame-rate 24` | | 约 10 秒 | `--num-frames 241 --frame-rate 24` | | 约 18 秒 | `--num-frames 441 --frame-rate 24` | > 也可以直接用 `--duration <秒数>` 让脚本自动换算（会规整到合法的 8n+1 帧数）。 ### 视频生成工作流 1. 调用 `generate_video.py`，脚本自动创建任务（`POST /v1/videos`）。 2. 用返回的 `video_id` 轮询查询（`GET /agnesapi?video_id=...`），进度打到 stderr。 3. 任务 `completed` 后，stdout 输出以 `MEDIA_URL: ` 开头的视频链接。 4. 加 `--save` 时额外下载并输出 `SAVED: ` 路径。 ### 视频注意事项 - `num_frames` 必须 ≤441 且满足 8n+1（如 81、121、241、441），脚本会自动规整非法值。 - 实际输出尺寸/时长以接口返回的 `size`、`seconds` 字段为准（服务端会标准化分辨率）。 - **参考图必须是可公网访问的 URL（`http`/`https`），不支持本地文件或 Base64**；本地图片请先用 `generate_image.py` 拿到公网 URL，或上传图床后再传入。 - 轮询期间对瞬时网络抖动有容错，会自动重试。