258 lines
10 KiB
Markdown
258 lines
10 KiB
Markdown
---
|
||
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 "一只圆润萌系的小火龙，大眼睛，贴纸风格"
|
||
```
|
||
|
||
指定尺寸：
|
||
|
||
```bash
|
||
python {baseDir}/scripts/generate_image.py --prompt "壮丽的山川日出" --size "1024x768"
|
||
```
|
||
|
||
### 图生图（保持一致性）
|
||
|
||
提供参考图 URL 或 `data:image` Base64，让新图沿用参考图的角色/构图：
|
||
|
||
```bash
|
||
python {baseDir}/scripts/generate_image.py \
|
||
--prompt "把这只小龙变成展翅的成年形态，保持配色和脸部不变" \
|
||
--image "https://example.com/baby-dragon.png"
|
||
```
|
||
|
||
可多次指定 `--image` 传入多张参考图。
|
||
|
||
### 下载保存到本地
|
||
|
||
加 `--save`，脚本会下载图片并保存，输出 `SAVED:<path>`：
|
||
|
||
```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`。
|
||
- `--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 展示：``。
|
||
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，或上传图床后再传入。
|
||
- 轮询期间对瞬时网络抖动有容错，会自动重试。
|
||
|
||
### 视频地址渲染
|
||
视频地址因为无法直接预览，需要调用`render_url`工具进行视频链接渲染。
|