2026-06-14 10:10:23 +08:00

10 KiB

Raw Blame History

name	description	category
agnes-image	使用 Agnes AI（OpenAI 兼容网关）生成与理解图片、生成视频。支持文生图、图生图（保持角色一致性）、贴纸/卡通形象生成、白底转透明 PNG、多模态图片理解（描述/分析/问答/OCR），以及文生视频、图生视频、多图视频、关键帧动画。	Creative Generation

Agnes Image

本 Skill 封装了 Agnes AI 的图像生成能力（模型 agnes-image-2.1-flash），接口兼容 OpenAI 风格，支持文生图、图生图，并内置「白底转透明」后处理，适合批量生成游戏/应用所需的角色、图标、贴纸等素材。

前置条件

设置 API Key（二选一）：

export AGNES_API_KEY="sk-xxxxxxxx"

或在每次调用时通过 --api-key 传入。

使用方法

文生图

生成单张图片，输出可访问的图片链接：

python {baseDir}/scripts/generate_image.py --prompt "一只圆润萌系的小火龙，大眼睛，贴纸风格"

指定尺寸：

python {baseDir}/scripts/generate_image.py --prompt "壮丽的山川日出" --size "1024x768"

图生图（保持一致性）

提供参考图 URL 或 data:image Base64，让新图沿用参考图的角色/构图：

python {baseDir}/scripts/generate_image.py \
  --prompt "把这只小龙变成展翅的成年形态，保持配色和脸部不变" \
  --image "https://example.com/baby-dragon.png"

可多次指定 --image 传入多张参考图。

下载保存到本地

加 --save，脚本会下载图片并保存，输出 SAVED:<path>：

python {baseDir}/scripts/generate_image.py --prompt "一只小猫贴纸" --save ./outputs/cat.png

白底转透明 PNG

配合 --save --transparent，自动把纯白背景抠成透明（保留主体内部白色，如白描边、白肚皮）：

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，值越大清除越彻底。

工作流

调用 generate_image.py 脚本。
脚本始终输出以 MEDIA_URL: 开头的图片链接，用 Markdown 展示：![image](URL)。
加了 --save 时，会额外下载到本地并输出以 SAVED: 开头的文件路径（MEDIA_URL 仍会一并输出）。
生成的图片链接来自 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

python {baseDir}/scripts/understand_image.py \
  --prompt "用中文描述这张图片的内容和风格" \
  --image "https://example.com/image.jpg"

理解本地图片

python {baseDir}/scripts/understand_image.py \
  --prompt "这是什么动物？什么颜色？" \
  --image-file ./outputs/fox.png

多图对比 / 信息提取

可多次指定 --image 或 --image-file 传入多张图片：

python {baseDir}/scripts/understand_image.py \
  --prompt "比较这两张图的差异" \
  --image-file ./a.png --image-file ./b.png

带系统提示

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 环境变量。

图片理解工作流

调用 understand_image.py 脚本。
脚本直接输出模型的文本回答（无前缀），可直接读取使用。
不传任何图片时，会退化为普通文本对话。

视频生成（异步）

使用 generate_video.py 生成视频（模型 agnes-video-v2.0）。视频生成是异步任务，脚本会自动创建任务并轮询，完成后输出视频链接。生成通常需要 1-3 分钟。

⚠️ 重要：视频生成用到的所有参考图（图生视频 / 多图 / 关键帧）必须是「可公网访问的图片 URL」（http:// 或 https://），不支持本地文件路径，也不支持 Base64。如果你手上只有本地图片，请先：

用 generate_image.py 生成图片，它返回的 MEDIA_URL 就是可直接使用的公网 URL；或

把本地图片上传到图床 / 对象存储（如 S3、R2）后，使用其公网 URL。

脚本会校验 --image 是否为合法 URL，传入本地路径会直接报错并给出提示。

文生视频

python {baseDir}/scripts/generate_video.py \
  --prompt "A cinematic shot of a cat walking on the beach at sunset, warm golden lighting" \
  --duration 5

图生视频（让单张图动起来）

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

多图视频（在多张图之间过渡）

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"

关键帧动画

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

下载保存

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 帧数）。

视频生成工作流

调用 generate_video.py，脚本自动创建任务（POST /v1/videos）。
用返回的 video_id 轮询查询（GET /agnesapi?video_id=...），进度打到 stderr。
任务 completed 后，stdout 输出以 MEDIA_URL: 开头的视频链接。
加 --save 时额外下载并输出 SAVED: 路径。

视频注意事项

num_frames 必须 ≤441 且满足 8n+1（如 81、121、241、441），脚本会自动规整非法值。
实际输出尺寸/时长以接口返回的 size、seconds 字段为准（服务端会标准化分辨率）。
参考图必须是可公网访问的 URL（http/https），不支持本地文件或 Base64；本地图片请先用 generate_image.py 拿到公网 URL，或上传图床后再传入。
轮询期间对瞬时网络抖动有容错，会自动重试。

视频地址渲染

视频地址因为无法直接预览，需要调用render_url工具进行视频链接渲染。

10 KiB Raw Blame History Unescape Escape