Skip to content
This repository was archived by the owner on Sep 7, 2026. It is now read-only.

Add agnes-media: image/video generation via Agnes AI API #11

Closed
Fectivnfy112357 wants to merge 1 commit into from
Closed

Add agnes-media: image/video generation via Agnes AI API #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions plugins/Fectivnfy112357/agnes-media/LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Fectivnfy112357

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
54 changes: 54 additions & 0 deletions plugins/Fectivnfy112357/agnes-media/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# agnes-media

Generate images and videos through the **Agnes AI API**: text-to-image,
image-to-image, multi-image composition, text-to-video, image-to-video and
keyframe animation — one stdlib-only Python script handles request building,
async task polling and result download; the agent only writes the prompt.

## The problem

Calling a production media-generation API from an agent means juggling
request payloads, async task queues, polling and file download — error-prone
and slow to repeat. agnes-media wraps both Agnes AI production models
(`agnes-image-2.1-flash` sync images, `agnes-video-v2.0` async videos) behind
a single script: `image` for seconds-fast images, `video` for minute-scale
videos with automatic frame-count math and built-in polling.

## Try it

Install from `/plugins` → **Local**, then ask:

```text
generate an image of a glowing floating city above a canyon at sunrise, cinematic, wide angle
```

**Expected result**: the generated image saved to the output directory
(default `~/Downloads`), with the script printing `ok=true` and the file
paths.

Direct usage:

```text
python <skill_dir>/scripts/agnes.py image --prompt "..." --size 2K --ratio 16:9
python <skill_dir>/scripts/agnes.py video --prompt "..." --duration 5
python <skill_dir>/scripts/agnes.py image --image a.png b.png --prompt "compose these"
```

## Requirements

- **An Agnes AI API key** (paid service) — provided via `--api-key`, the
`AGNES_API_KEY` environment variable, or an `.env` file.
- Python 3.8+ (stdlib-only script).

## Data and network

- The script talks only to the Agnes AI API (`apihub.agnes-ai.com`).
- The API key is read from the user's own environment/config; it is never
stored in this plugin's directory.
- Local input images are sent to the API as data URIs for image-to-image /
video tasks.
- No telemetry, no other third-party services.

## License

MIT
12 changes: 12 additions & 0 deletions plugins/Fectivnfy112357/agnes-media/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "agnes-media",
"version": "1.0.0",
"description": "Generate images and videos through the Agnes AI API: text-to-image, image-to-image, multi-image composition, text-to-video, image-to-video and keyframe animation — one Python script (stdlib-only) handles request building, async task polling and result download; the agent only writes the prompt.",
"author": {
"name": "Fectivnfy112357",
"url": "https://github.com/Fectivnfy112357"
},
"license": "MIT",
"keywords": ["agnes-ai", "image-generation", "video-generation", "text-to-image", "text-to-video"]
}
102 changes: 102 additions & 0 deletions plugins/Fectivnfy112357/agnes-media/skills/agnes-media/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
name: agnes-media
description: Use when 用户用 Agnes AI 生成图片或视频。跑 scripts/agnes.py。
version: 1.0.0
author: Fectivnfy112357
license: MIT
---

# Agnes AI 生图 / 生视频

## Overview

封装 Agnes AI 两个生产模型的调用。Agent 只负责写 prompt 和传参数，脚本接管请求构建、任务轮询、结果下载、错误处理。

- **图像** `agnes-image-2.1-flash`：文生图 / 图生图 / 多图合成，URL 或 Base64 输出，同步（秒级）。
- **视频** `agnes-video-v2.0`：文生视频 / 图生视频 / 关键帧动画，异步任务（先创建再轮询）。

脚本：`scripts/agnes.py`，标准库实现，零第三方依赖，Python 3.8+ 均可。

## When to Use

- 用户要「生成一张图」→ 文生图；「按描述改这张图」→ 图生图；「把几张图合成」→ 多图合成。
- 用户要「生成视频」→ 文生视频；「让这张图动起来」→ 图生视频；「两帧/多帧之间过渡」→ 关键帧动画。
- 写 prompt 前先读 `references/prompt-styles.md`（推荐结构 + 示例）。
- **不要用本 skill 做**：工具/模型选型与对比 → `ai-media-generation-tools` skill。

## 前置：API Key

脚本按顺序读取：`--api-key` 参数 → `AGNES_API_KEY` 环境变量 → `~/.hermes/.env` 文件里的 `AGNES_API_KEY`。

key 已通过环境变量 `AGNES_API_KEY` 提供（`~/.bashrc` 里 export），脚本开箱即用。想迁移到 Hermes 统一管理，可用 `hermes config set AGNES_API_KEY=xxx` 写进 `~/.hermes/.env`——脚本会直接解析该文件。
明文不进 skill 目录（避免被 skill 同步/分享时泄露）。

## 固定流程

统一脚本 + 两个子命令：

```
python <skill_dir>/scripts/agnes.py image ... # 图像，同步
python <skill_dir>/scripts/agnes.py video ... # 视频，异步（脚本内部轮询）
```

`<skill_dir>` = 本 skill 的安装目录（SKILL.md 所在目录；由宿主的技能加载器提供，如 `skill_view` 的 `skill_dir` / `resourceBase` 字段）。执行脚本统一用：`python "<skill_dir>/scripts/agnes.py" ...`。

### 图像（同步，秒级返回）

```bash
python .../scripts/agnes.py image \
--prompt "日出薄雾峡谷上方的发光浮空城市，电影级写实，广角，高视觉密度" \
--size 2K --ratio 16:9 --out ~/Downloads
```

| 参数 | 说明 |
|---|---|
| `--prompt` | 必填，风格见 prompt-styles.md |
| `--size` | 档位 `1K/2K/3K/4K`，默认 `1K` |
| `--ratio` | `1:1/3:4/4:3/16:9/9:16/2:3/3:2/21:9`，默认 `1:1` |
| `--image` | 图生图/多图合成：本地路径或 URL，可多次传入；本地文件自动转 data URI |
| `--format` | `url`（默认）或 `b64` |
| `--out` | 输出目录，默认 `~/Downloads` |

### 视频（异步，分钟级，脚本自动轮询）

```bash
python .../scripts/agnes.py video \
--prompt "A young astronaut walking across a red desert planet, dust blowing in the wind, slow cinematic tracking shot, dramatic sunset lighting, realistic sci-fi style" \
--duration 5 --out ~/Downloads
```

| 参数 | 说明 |
|---|---|
| `--prompt` | 必填 |
| `--image` | 图生视频：输入图（本地路径或 URL） |
| `--keyframes` | 关键帧动画：多个输入图（本地或 URL，至少 2 个） |
| `--duration` | 目标时长（秒），脚本自动算 `num_frames`（8n+1 且 ≤441） |
| `--num-frames` / `--frame-rate` | 手动指定（高级，绕过 --duration） |
| `--width` / `--height` | 默认 `1152x768` |
| `--seed` / `--negative-prompt` | 可复现 / 排除内容 |

## 提示词风格

→ `references/prompt-styles.md`：文生图 / 图生图 / 多图合成 / 高信息密度 + 文生视频 / 图生视频 / 关键帧动画的推荐结构 + 中英文示例。**写 prompt 前先读，套结构而非空想。**

## 参数详情

→ `references/api-reference.md`：尺寸档位表、ratio 输出尺寸表、视频时长表、任务状态、错误码、定价。

## Common Pitfalls

1. **图像 `response_format` 别放顶层**：脚本已按正确位置处理（url→`extra_body.response_format`；文生 b64→顶层 `return_base64`；图生 b64→`extra_body.response_format=b64_json`）。不要手改 payload。
2. **图生图别传 `tags:["img2img"]`**：文档明确不需要，脚本也不会传。
3. **视频 `num_frames` 必须满足 `8n+1` 且 ≤441**：用 `--duration` 让脚本算，别手填 120 这类非法值。
4. **视频是异步的**：脚本内部轮询（5s 间隔，最长 10 分钟）。不要以为无返回就是失败。
5. **本地图片**：图像/视频脚本都会把本地文件自动转 data URI，实测图像与视频 API 均接受（视频网关会把 data URI 落盘成内部 URL 再处理）。无需手动上传图床。
6. **选型问题别混进来**：本 skill 只执行生成；工具/模型选型走 `ai-media-generation-tools`。

## Verification Checklist

- [ ] 输出文件存在于 `--out` 目录且非空（图像 >10KB，视频 >100KB）
- [ ] 视频任务 `status=completed`，`metadata.url` 已下载
- [ ] 脚本末尾打印的 JSON 里 `ok=true` 且含 `files` 绝对路径
- [ ] 用 `vision_analyze` / `video_analyze` 抽查成片质量
118 changes: 118 additions & 0 deletions plugins/Fectivnfy112357/agnes-media/skills/agnes-media/references/api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# Agnes API 参数参考

整理自 Agnes 官方文档。脚本已封装这些参数，此处供 Agent 查表（尺寸映射、时长、状态、错误码）。

## 图像 API

- Endpoint：`POST https://apihub.agnes-ai.com/v1/images/generations`
- 模型：`agnes-image-2.1-flash`
- 请求头：`Authorization: Bearer <KEY>`、`Content-Type: application/json`

### 参数

| 参数 | 必填 | 说明 |
|---|---|---|
| `model` | 是 | `agnes-image-2.1-flash` |
| `prompt` | 是 | 生成/编辑指令 |
| `size` | 是 | 档位 `1K/2K/3K/4K`，也兼容 `1024x768` 历史写法（可能被标准化） |
| `ratio` | 否 | `1:1/3:4/4:3/16:9/9:16/2:3/3:2/21:9`，默认 `1:1` |
| `return_base64` | 否 | 文生图 Base64 输出用 |
| `extra_body.image` | 否 | 图生图/多图合成输入图（URL 或 Data URI），数组 |
| `extra_body.response_format` | 否 | `url` 或 `b64_json` |

### 输出尺寸表（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 显示素材请用 `size=2K, ratio=16:9`（得 2624x1472）再下游裁剪。

### 响应

- URL 输出：`data[0].url`
- Base64 输出：`data[0].b64_json`

### 关键约束

- `response_format` 不能放顶层：url → `extra_body.response_format`；文生 b64 → 顶层 `return_base64`；图生 b64 → `extra_body.response_format=b64_json`。
- 图生图不要传 `tags:["img2img"]`。
- 输入图无法公开访问时用 Data URI。
- 客户端超时建议 60–360s。

---

## 视频 API

- 创建：`POST https://apihub.agnes-ai.com/v1/videos`
- 查结果（推荐）：`GET https://apihub.agnes-ai.com/agnesapi?video_id=<VIDEO_ID>`
- 查结果（兼容旧版）：`GET https://apihub.agnes-ai.com/v1/videos/<TASK_ID>`
- 模型：`agnes-video-v2.0`

### 创建参数

| 参数 | 类型 | 说明 |
|---|---|---|
| `model` | string | `agnes-video-v2.0` |
| `prompt` | string | 视频内容描述 |
| `image` | string | 图生视频输入图 URL |
| `mode` | string | `ti2vid` 或 `keyframes` |
| `height` | int | 默认 768 |
| `width` | int | 默认 1152 |
| `num_frames` | int | ≤441 且 8n+1 |
| `frame_rate` | number | 1–60 |
| `num_inference_steps` | int | 推理步数 |
| `seed` | int | 可复现 |
| `negative_prompt` | string | 排除内容 |
| `extra_body.image` | array | 关键帧模式输入图 URL 数组 |
| `extra_body.mode` | string | `keyframes` |

### 尺寸标准化

提交的宽高会被映射到最近的 480p/720p/1080p 标准档。以响应 `size` / `seconds` / `metadata.size_mapping` 为准。

### 时长控制

`seconds = num_frames / frame_rate`

| 目标时长 | 推荐参数 |
|---|---|
| 约 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` |

### 任务状态

| 状态 | 说明 |
|---|---|
| `queued` | 排队中 |
| `in_progress` | 生成中 |
| `completed` | 成功。视频 URL 在顶层 `url` 字段（文档示例写 `metadata.url`，实测无 `metadata` 包装，脚本两者都兼容） |
| `failed` | 失败（`error` 字段给原因） |

### 错误码

| 码 | 说明 |
|---|---|
| 400 | 参数无效 |
| 401 | key 未授权 |
| 404 | 任务/视频未找到 |
| 500 | 服务器错误 |
| 503 | 繁忙，稍后重试 |

---

## 定价

| 类型 | 标准价 | 当前价 |
|---|---|---|
| 图像 | $0.003/张 | $0/张 |
| 视频 | $0.005/秒 | $0/秒 |
Loading