skill

agnes-media-skill

封装免费的Agnes AI 图像与视频生成技能

Ryderey/agnes-media-skillcommunitylistedunreviewed

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/Ryderey/agnes-media-skill itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 25, 2026

Agnes Media Generation

English | 简体中文

通过标准 Agent Skill 或零依赖 Python CLI，调用 Agnes AI 生成、编辑图像与视频。

能力速览

能力 / 模型	项目状态	主要用途与边界	使用入口
Image 2.5 Flash	已支持 · 当前默认	默认图像模型，无需模型参数；文生图、图生图与多图合成	默认图像使用
Image 2.1 Flash	已支持 · 旧模型，显式选择	文生图、图像编辑、多图合成；使用 `--model agnes-image-2.1-flash`	调用旧模型
Video 2.5 Flash	已支持 · 唯一视频模型	text / keyframe / reference；4–12 秒、720P	视频使用
Video 2.0	已下线 · 不再支持	官方已停止服务，CLI 已移除该模型；请改用 Video 2.5 Flash	视频使用
视频异步任务	已支持	提交、查询、等待和下载	任务管理
本地结果保存	已支持	图像与视频保存到指定目录，返回绝对路径	输出目录

运行环境：Python 3.10+，Windows / macOS / Linux，无第三方 Python 依赖。

快速开始

1. 安装 Skill

从下方安装说明中选择你正在使用的 Agent。大多数用户只需复制一条命令或一段提示词。

2. 获取 API Key

前往 Agnes AI 注册并获取 API Key。

3. 配置 API Key

macOS / Linux（仅对当前终端会话生效）：

export AGNES_API_KEY="your_agnes_api_key"

Windows PowerShell（仅对当前终端会话生效）：

$env:AGNES_API_KEY = "your_agnes_api_key"

如需永久生效，请根据所用 shell 选择一组命令。

macOS / Linux（bash）：

echo 'export AGNES_API_KEY="your_agnes_api_key"' >> ~/.bashrc
source ~/.bashrc

macOS / Linux（zsh）：

echo 'export AGNES_API_KEY="your_agnes_api_key"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell：

[Environment]::SetEnvironmentVariable("AGNES_API_KEY", "your_agnes_api_key", "User")

保存后请重新打开终端和 Agent，使新环境变量生效。

请通过环境变量配置密钥，切勿将 Key 写入仓库或提交到公开代码。

4. 使用

用 Agnes 生成一张 16:9、2K 的电影感雪山日出壁纸。

用 Agnes 把这张本地图片改成赛博朋克夜景，保留人物面部和构图。

用 Agnes 将两张角色图片合成到同一个奇幻战斗场景中。

用 Agnes 生成一个 5 秒视频：红色纸船在平静水面缓慢漂流，固定镜头，柔和日光。

Agent 会在请求明确提及 Agnes，且任务属于图像或视频的生成、编辑、合成或动画时自动触发本 Skill。普通图像请求无需指定模型，默认使用 Image 2.5 Flash；需要旧模型时在请求中写明模型版本即可（见调用旧模型）。

Workbuddy 用户

如果你通过 ZIP 压缩包导入此 Skill，请先确认 <available_skills> 列表中已包含 agnes-media-generation。随后建议在请求前显式调用，以确保当前对话直接使用该技能：

/agnes-media-generation 用 Agnes 生成一张极简风格的蓝色圆形图标。

提示词语言

默认情况下，Skill 会将中文等非英文提示词自动翻译成英文并优化后再提交，以获得最佳生成效果：

自动翻译（默认）：非英文提示词自动译为英文并隐式优化。
保留原文：需要保持原语言时，请在请求中明确说明，例如"保持原语言"。
双语对照：也可以要求 Agent 先展示原文与英文译文的对比，确认后再生成。

安装

只需选择你正在使用的 Agent，不需要执行所有方式。安装 Skill 前，请确保本机已有 Python 3.10 或更高版本：

python --version

Windows 如果没有 python 命令，可运行 py -3 --version。

OpenAI Codex（推荐方式）

在 Codex 对话中发送：

$skill-installer 请从 https://github.com/Ryderey/agnes-media-skill 安装技能 agnes-media-generation。

Codex 通常会自动发现新 Skill；如果没有出现，重启 Codex 后再试。

Claude Code（推荐方式）

在 Claude Code 中依次运行：

/plugin marketplace add Ryderey/agnes-media-skill
/plugin install agnes-media-generation@agnes-media-skill

如果安装摘要提示重新加载，再运行 /reload-plugins。也可以运行 /plugin 打开插件管理器，在 Discover 标签页中安装。

其他支持 Skill 的 Agent

让 Agent 替你完成安装。根据希望生效的范围，复制下面其中一段提示词即可。

用户级安装（推荐）：安装一次，之后在所有项目中都可使用。

请将 https://github.com/Ryderey/agnes-media-skill 中的 agnes-media-generation 安装到当前 Agent 的用户级 skills 目录，重载并验证后，告诉我技能名称、如何配置（如 API Key）以及使用示例。

项目级安装：只在当前项目中使用，适合团队随项目共享。

请将 https://github.com/Ryderey/agnes-media-skill 中的 agnes-media-generation 安装到当前项目的 skills 目录，重载并验证后，告诉我技能名称、如何配置（如 API Key）以及使用示例。

如果国内 GitHub 访问较慢，可将提示词中的仓库地址替换为 Gitee 镜像：https://gitee.com/zzol_wow/agnes-media-skill.git。

验证安装

在 Agent 中输入：

用 Agnes 生成一张极简风格的蓝色圆形图标。

如果 Agent 找不到 Skill：

确认安装目录中直接存在 SKILL.md，且文件名大小写完全一致。
Codex：重启应用；Claude Code：运行 /reload-plugins。
出现 AGNES_API_KEY 错误时，请在启动 Agent 的同一个终端中重新设置环境变量。

如果目标目录已存在，说明可能已经安装过。进入该目录运行 git pull 即可更新，无需再次克隆。

提示词最佳实践

以下内容来自 Agnes 官方文档。Skill 默认会将非英文提示词自动翻译成英文并优化，因此你通常可以直接用中文描述需求；了解下列结构有助于写出效果更好、结果更可控的提示词。

图像生成

场景	推荐结构
文生图	[主体] + [场景 / 环境] + [风格] + [光照] + [构图] + [质量要求]
图生图	[改变要求] + [新风格 / 场景] + [需要添加或移除的元素] + [需要保留的元素]
多图合成	[参考图角色] + [目标场景] + [图像之间的关系] + [风格 / 光照 / 构图]
高信息密度	清晰描述视觉层次：主要主体、背景环境、重要次要细节、风格、光照与构图约束

官方示例：

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

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

将第一张图作为主要角色，第二张图作为产品参考，生成一张电影级活动海报，保留角色身份和产品外形，使用自然光照和干净的商业构图。

视频生成

Agnes Video 2.5 Flash 与 Agnes Video 2.5 使用相同的提示词方法。Skill 会按以下顺序整理用户描述，只补充与需求有关的部分：

顺序	推荐内容
1. 主体与场景	人物或物体、环境、时间
2. 动作与变化	主体如何运动、场景如何变化
3. 镜头语言	景别，以及固定、推、拉、摇、移或跟拍
4. 视觉风格	光线、色彩、材质、写实程度与氛围
5. 声音与节奏	环境声、动作声或参考音频的节奏（需要时）
6. 一致性	需要保持不变的人物外观、产品细节或构图

不同模式还应说明素材如何参与生成：

模式	优化重点
`text`	完整描述主体、动作、镜头和风格；只在需要时加入声音
`keyframe`	描述首尾帧之间的动作与镜头过渡，以及必须保持一致的元素
`reference`	明确每项素材用于人物、外观、风格、动作还是节奏，并在提示词中使用对应占位符

优化示例：

夜晚森林中，三只猫组成微型铜管乐队向前行进，镜头平稳后退，月光穿过树叶，保持角色外观一致，自然脚步声与乐器声。

人物从首帧姿态自然转身走向窗边，衣物和头发运动真实，镜头缓慢推进，保持人物外观一致，并平滑过渡到尾帧构图。

以 <Picture 1> 作为角色与服装参考，保持面部和服装一致，让人物在花田中自然奔跑，并使动作节奏与 <Audio 1> 同步，低机位跟拍。

<Picture N> 和 <Audio N> 分别按图片、音频输入顺序从 1 编号，翻译提示词时应原样保留。Flash 不支持 <Video N>；相较完整 2.5 模型，它还固定为 720P，且参考图最多 5 张。

默认图像：Image 2.5 Flash

三个图像命令（image-generate、image-generate-v2、image-edit）默认都使用 Image 2.5 Flash（agnes-image-2.5-flash）。普通使用不需要填写模型参数：

python scripts/agnes_media.py image-generate --prompt "A glass cube on a clean studio background"

python scripts/agnes_media.py image-generate-v2 --prompt "A cinematic floating city above a misty canyon"

--size：推荐 1K / 2K / 3K / 4K，未指定时默认 1K；精确尺寸（如 1024x1024）也会被接受，服务端可能做归一化。原生输出尺寸组合以官方文档为准。
--ratio：可选，支持 1:1、3:4、4:3、16:9、9:16、2:3、3:2、21:9，未指定时默认为 1:1。
图生图与多图合成：把输入图放入官方 extra_body.image 字段；本地路径、Data URI 与公开 URL 均可（本地文件会自动转成 Data URI）。输入图数量限制以官方定价与文档为准。
编辑任务要说明"改变什么、保留什么"；多图任务按输入顺序说明每张图的作用。
结果返回 image_urls 与 local_paths；若 save_errors 非空，说明生成成功但本地保存失败，仍可继续使用远程 URL。

迁移说明：如果你之前显式设置了 AGNES_IMAGE_MODEL 或 AGNES_IMAGE_MODEL_V2，它们仍优先生效（详见配置）。希望恢复新默认时，请清除这两个环境变量，或在对应命令中用 --model agnes-image-2.5-flash 覆盖。需要保持旧模型行为的脚本，在命令中增加 --model agnes-image-2.1-flash 即可。

调用旧模型：Image 2.1 Flash

需要 Image 2.1 Flash 时，在任何图像命令显式传入模型 ID，同时按旧模型规则选择尺寸与比例：

python scripts/agnes_media.py image-generate --model agnes-image-2.1-flash \
  --prompt "A glass cube on a clean studio background" \
  --size 1024x1024

python scripts/agnes_media.py image-generate-v2 --model agnes-image-2.1-flash \
  --prompt "A cinematic floating city above a misty canyon" \
  --size 2K \
  --ratio 16:9

python scripts/agnes_media.py image-edit --model agnes-image-2.1-flash \
  --image ./source.png \
  --prompt "Replace the daytime sky with a starry night while preserving the buildings"

旧模型保持原有默认值：image-generate / image-edit 未指定尺寸时使用 1024x1024，image-generate-v2 使用 1K 且默认比例 1:1。旧模型不校验比例取值，参数行为与升级前一致。

唯一视频模型：Video 2.5 Flash

普通视频请求使用 agnes-video-2.5-flash，无需指定模型；这也是 CLI 唯一支持的视频模型。你可以在请求中明确写出 video 2.5 flash（空格或连字符均可）：

/agnes-media-generation 生成一个 5 秒视频：红色纸船在平静水面缓慢漂流。

/agnes-media-generation video 2.5 flash 生成视频：宇航员走过红色荒漠，缓慢跟拍。

用 Agnes Video-2.5-Flash 生成视频：海浪轻拍礁石，固定镜头。

Flash 支持 text（文生视频）、keyframe（首帧 / 尾帧）和 reference（最多 5 张参考图，可附参考音频）三种模式；时长为 4–12 秒，分辨率固定为 720P，支持 21:9、16:9、4:3、1:1、3:4、9:16。所有素材 URL 必须是公开 HTTPS 地址。

python scripts/agnes_media.py video-generate \
  --mode text --duration 5 --aspect-ratio 16:9 \
  --prompt "A red paper boat drifts slowly across calm water, fixed medium-wide shot, soft daylight, gentle ripples, realistic cinematic style"

python scripts/agnes_media.py video-generate \
  --mode keyframe \
  --first-frame https://example.com/first.png \
  --last-frame https://example.com/last.png \
  --prompt "The character turns naturally and walks toward the window, slow camera push-in, preserve identity and clothing, transition smoothly to the last-frame composition"

python scripts/agnes_media.py video-generate \
  --mode reference \
  --reference-image https://example.com/character.png \
  --reference-audio https://example.com/music.mp3 \
  --prompt "Use <Picture 1> as the character reference, preserve the face and outfit, walk forward in sync with <Audio 1>, low-angle tracking shot"

Flash 请求失败时会直接报告原因，不会静默改用其他模型。价格与限额以官方文档为准。

从 Video 2.0 迁移：Agnes 已下线 Video 2.0，CLI 不再接受 --model agnes-video-v2.0，并移除了 --image、--frame-rate、--negative-prompt、--num-inference-steps 与视频命令的 --extra-body。图生视频与首尾帧改用 --mode keyframe 配 --first-frame / --last-frame；参考图、参考音频改用 --mode reference 配重复的 --reference-image / --reference-audio。Flash 固定 720P、单段 4–12 秒，需要更长片段时分段生成再拼接。video-status / video-wait 同样拒绝旧模型，因此升级前已提交的 2.0 任务无法再用本 CLI 查询。

视频任务管理

长视频任务可以先提交再查询，或提交后等待完成并下载：

video-submit：提交任务，返回 task_id / video_id 与 status。
video-status VIDEO_ID：按 ID 查询进度（可选 --model）。
video-wait VIDEO_ID：轮询直到完成并下载。
video-generate：提交、等待、下载一步完成（默认用法）。

python scripts/agnes_media.py video-submit --prompt "A red paper boat drifts slowly across calm water, fixed camera" --mode text --duration 5 --aspect-ratio 16:9

python scripts/agnes_media.py video-wait video_id_here --timeout-seconds 600 --poll-interval-seconds 5

video-status / video-wait 按 Flash 查询。轮询会自动重试 HTTP 429 / 503。超时后回报 video_id，稍后可继续查询。

直接使用 CLI

Skill 内置标准库 CLI，无需 Agent 也可以独立运行：

任务	命令
图像 / 图生图	`image-generate --prompt ... [--size ...] [--ratio ...] [--model ...]`
高清图像	`image-generate-v2 --prompt ... [--size 1K]–[4K] [--ratio ...] [--model ...]`
编辑 / 合成图像	`image-edit --prompt ... --image 图 [--image 图 ...] [--model ...]`
提交视频任务	`video-submit --prompt ... [--model ...]`
查询视频任务	`video-status VIDEO_ID [--model ...]`
等待并下载视频	`video-wait VIDEO_ID [--model ...]`
一步生成视频	`video-generate --prompt ... [--model ...]`

模型与参数细节分别见默认图像、旧图像模型、视频模型等章节。查看全部命令：

python scripts/agnes_media.py --help
python scripts/agnes_media.py image-edit --help
python scripts/agnes_media.py video-generate --help

Windows 也可以使用 py -3 代替 python。

配置

环境变量	必填	默认值	说明
`AGNES_API_KEY`	是	—	Agnes API Key
`AGNES_BASE_URL`	否	`https://api.agnes-ai.cn/v1`	API Base URL
`AGNES_IMAGE_MODEL`	否	`agnes-image-2.5-flash`	标准图像模型（默认 Image 2.5 Flash）
`AGNES_IMAGE_MODEL_V2`	否	`agnes-image-2.5-flash`	高分辨率图像模型（默认 Image 2.5 Flash）
`AGNES_VIDEO_MODEL`	否	`agnes-video-2.5-flash`	视频模型（仅接受 `agnes-video-2.5-flash`）
`AGNES_OUTPUT_DIR`	否	当前目录下的 `outputs`	媒体保存根目录

默认使用中国区接口 https://api.agnes-ai.cn/v1。切换平台时，请同时设置对应的 AGNES_BASE_URL，并使用该平台签发的 API Key；不同平台的密钥不互通。

图像命令的模型优先级：--model → AGNES_IMAGE_MODEL（或 AGNES_IMAGE_MODEL_V2）→ 内置默认 agnes-image-2.5-flash。AGNES_IMAGE_MODEL_V2 不会隐式回退到 AGNES_IMAGE_MODEL，两个配置彼此独立。
视频仅支持 agnes-video-2.5-flash。优先级仍是 --model → AGNES_VIDEO_MODEL → 内置默认，但取值必须是该模型；已下线的 agnes-video-v2.0 会在发出请求前直接报错，不会静默改用其他模型。
环境变量是显式保存的模型偏好，继续优先生效。希望使用新默认时，清除对应的模型变量即可（本次升级不会自动改写你的环境配置）：

Remove-Item Env:AGNES_IMAGE_MODEL -ErrorAction SilentlyContinue
Remove-Item Env:AGNES_IMAGE_MODEL_V2 -ErrorAction SilentlyContinue
Remove-Item Env:AGNES_VIDEO_MODEL -ErrorAction SilentlyContinue

unset AGNES_IMAGE_MODEL AGNES_IMAGE_MODEL_V2 AGNES_VIDEO_MODEL

若模型变量写在 PowerShell 用户环境或 shell 启动配置中，需要你同步移除对应覆盖后重开终端 / Agent。model 返回字段始终展示实际提交的模型 ID，便于发现仍生效的旧环境配置。

输出目录

默认保存位置：

outputs/
├── images/
└── videos/

通过 AGNES_OUTPUT_DIR 可指定其他目录。CLI 始终输出单个 JSON 对象，并在成功结果中返回媒体的绝对本地路径。

使用限制

图像

Image 2.5 Flash 的 --size 推荐 1K–4K（默认 1K）；--ratio 仅支持 1:1、3:4、4:3、16:9、9:16、2:3、3:2、21:9，非法取值会在网络调用前报错。
图像输入支持公开 HTTP(S) URL、Data URI 和本地文件路径；多图按输入顺序提交。
Image 2.1 Flash 为旧模型，需在命令中显式指定 --model agnes-image-2.1-flash。
当前不支持基于蒙版的局部编辑。
新模型上线与验证情况见更新日志；2026-09-12 线上冒烟测试已通过（默认 2.5 的文生图、高清、单图编辑、多图合成与旧模型调用）。

视频

视频输入媒体必须是公开可访问的 HTTPS URL。
2.5 Flash 时长为 4–12 秒的整数、固定 720P，参考图最多 5 张；旧 Video 2.0 的帧数对齐与 --frame-rate 等参数已随模型下线一并移除。
API 价格、模型能力和限额以 Agnes 官方文档为准。

注意： 2.5 Flash 的音轨由模型随机合成，其中的"人声"只是含糊的拟声，不会按脚本准确朗读对白。需要台词时，建议在后期静音原音轨，再另行添加字幕或免版权 TTS 配音（如 edge-tts）。

License

MIT