# Sfg Skills Agnes

> |

- **Type:** Skill
- **Install:** `agentstack add skill-fuzhengwei-xfg-skills-agnes-xfg-skills-agnes`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fuzhengwei](https://agentstack.voostack.com/s/fuzhengwei)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [fuzhengwei](https://github.com/fuzhengwei)
- **Source:** https://github.com/fuzhengwei/xfg-skills-agnes

## Install

```sh
agentstack add skill-fuzhengwei-xfg-skills-agnes-xfg-skills-agnes
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Agnes AI 图像与视频生成技能

通过 Agnes AI API 生成高质量图片和视频。支持文生图、图生图、文生视频、图生视频、多图视频和关键帧动画。

## API Key 配置

> ⚠️ API Key 仅保存在本地 `~/.agnes/config.json`，不会被提交到版本控制。

### 静默检查优先

调用图像/视频生成前，**不要主动询问 API Key**。按以下逻辑处理：

1. **静默检查**：直接读取 `~/.agnes/config.json`，如果已有 `api_key` 字段且非空，直接使用，无需提示用户
2. **首次配置**：仅当本地不存在配置文件或 `api_key` 为空时，才引导用户设置：
   ```bash
   python3 "{SKILL_DIR}/scripts/agnes_config.py" set --api-key YOUR_API_KEY
   ```
3. **Key 失效**：仅当 API 返回 401 错误时，才提示用户 Key 可能失效，引导重新配置

### 配置管理命令

```bash
# 查看当前配置
python3 "{SKILL_DIR}/scripts/agnes_config.py" show

# 设置/更新 API Key
python3 "{SKILL_DIR}/scripts/agnes_config.py" set --api-key YOUR_API_KEY

# 删除配置
python3 "{SKILL_DIR}/scripts/agnes_config.py" delete
```

---

## 一、图像生成（agnes-image-2.1-flash）

### 1.1 文生图

根据文本提示词生成图片：

```bash
python3 "{SKILL_DIR}/scripts/agnes_image.py" \
  --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" \
  --size "1024x768"
```

### 1.2 图生图

基于已有图片进行风格转换或编辑：

```bash
python3 "{SKILL_DIR}/scripts/agnes_image.py" \
  --prompt "Transform the scene into a rain-soaked cyberpunk night with neon reflections while preserving the original composition" \
  --size "1024x768" \
  --image "https://example.com/input-image.png"
```

也支持本地图片（自动转 Base64）：

```bash
python3 "{SKILL_DIR}/scripts/agnes_image.py" \
  --prompt "Make the object orange while preserving the original composition" \
  --size "1024x768" \
  --image "/path/to/local/image.png"
```

### 1.3 图像参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--size` | 1024x768 | 输出图片尺寸 |
| `--output-format` | url | 输出格式：`url` 或 `b64_json` |
| `--output-dir` | 当前目录 | 图片保存目录（url 模式自动下载） |
| `--no-download` | false | 仅返回 URL 不下载图片 |

### 1.4 提示词优化

生成图像前，**必须帮助用户优化提示词**：

**文生图推荐结构**：
```
[主体] + [场景/环境] + [风格] + [光照] + [构图] + [质量要求]
```

**图生图推荐结构**：
```
[修改要求] + [新风格/新场景] + [添加/移除的元素] + [需要保留的元素]
```

如果用户提供的提示词过于简单，主动扩展为更完整的描述后再调用 API。

### 1.5 结果展示

图像生成成功后，使用 Markdown 图片格式展示：

```markdown

```

---

## 二、视频生成（agnes-video-v2.0）

视频生成是**异步任务**，需要先创建任务再轮询查询结果。

### 2.1 文生视频

根据文本提示词生成视频：

```bash
python3 "{SKILL_DIR}/scripts/agnes_video.py" \
  --prompt "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion" \
  --width 1152 --height 768 \
  --num-frames 121 --frame-rate 24
```

### 2.2 图生视频

将静态图片动画化：

```bash
python3 "{SKILL_DIR}/scripts/agnes_video.py" \
  --prompt "The woman slowly turns around and looks back at the camera, natural facial expression, cinematic camera movement" \
  --image "https://example.com/image.png" \
  --num-frames 121 --frame-rate 24
```

### 2.3 多图视频生成

使用多张参考图片生成视频：

```bash
python3 "{SKILL_DIR}/scripts/agnes_video.py" \
  --prompt "Create a smooth transformation scene between the two reference images, cinematic lighting, consistent character identity" \
  --images "https://example.com/image1.png,https://example.com/image2.png" \
  --num-frames 121 --frame-rate 24
```

### 2.4 关键帧动画

在关键帧之间生成平滑过渡：

```bash
python3 "{SKILL_DIR}/scripts/agnes_video.py" \
  --prompt "Generate a smooth cinematic transition between the keyframes, maintaining visual consistency and natural camera movement" \
  --images "https://example.com/keyframe1.png,https://example.com/keyframe2.png" \
  --mode keyframes \
  --num-frames 121 --frame-rate 24
```

### 2.5 视频参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--width` | 1152 | 视频宽度 |
| `--height` | 768 | 视频高度 |
| `--num-frames` | 121 | 视频帧数（必须 ≤ 441 且满足 8n+1） |
| `--frame-rate` | 24 | 视频 FPS（1-60） |
| `--seed` | 随机 | 随机种子，用于可复现结果 |
| `--negative-prompt` | 无 | 负向提示词 |
| `--mode` | ti2vid | 生成模式（ti2vid / keyframes） |
| `--poll-interval` | 10 | 轮询间隔秒数 |
| `--timeout` | 600 | 最大等待秒数 |

### 2.6 常用时长参数

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

### 2.7 提示词优化

**文生视频推荐结构**：
```
[主体] + [动作] + [场景] + [镜头运动] + [光照] + [风格]
```

**图生视频推荐结构**：
```
描述哪些内容需要运动 + 哪些主体元素需要保持稳定
```

如果用户提供的提示词过于简单，主动扩展为更完整的描述后再调用 API。

### 2.8 视频生成等待过程

视频生成通常需要 **1-5 分钟**。创建任务后脚本会自动轮询等待，并在等待期间展示进度：

```
🎬 视频生成任务已创建
   任务 ID: video_xxxxxx
   状态: queued → in_progress
   进度: ████████░░ 80%
   预计等待: ~2 分钟
```

### 2.9 结果展示

视频生成成功后，直接提供视频链接：

```
🎬 视频已生成完成！

🔗 视频链接: https://storage.googleapis.com/agnes-aigc/aigc/videos/xxx.mp4
📏 分辨率: 1280x768
⏱️ 时长: 10.0 秒
```

### 2.10 仅创建任务（不等待）

如果不想阻塞等待，可以使用 `--no-wait` 参数：

```bash
python3 "{SKILL_DIR}/scripts/agnes_video.py" \
  --prompt "..." \
  --no-wait
```

稍后手动查询：

```bash
python3 "{SKILL_DIR}/scripts/agnes_video.py" \
  --query "video_xxxxxx"
```

---

## 三、分辨率与宽高比

### 图像

推荐尺寸：`1024x768`（4:3）、`768x1024`（3:4）、`1024x576`（16:9）、`576x1024`（9:16）、`1024x1024`（1:1）

### 视频

系统会自动标准化到最接近的标准规格：

| 宽高比 | 推荐场景 | 推荐尺寸 |
|--------|----------|----------|
| 16:9 | 横屏视频、YouTube | 1152x768 |
| 9:16 | 竖屏短视频、TikTok | 768x1152 |
| 1:1 | 方形视频、社交媒体 | 768x768 |
| 4:3 | 通用展示 | 1152x768 |
| 3:4 | 竖向展示 | 768x1152 |

---

## 四、完整工作流

1. **静默检查 API Key**：直接执行脚本（脚本自动读取本地配置）；仅当脚本报错提示未配置时才引导用户设置 Key
2. **优化提示词**：将用户简单的描述扩展为完整的专业提示词
3. **调用 API**：执行生成脚本
4. **等待结果**：视频需轮询等待，图像直接返回
5. **展示结果**：图像用 `` 格式，视频用链接格式
6. **处理 401 错误**：如果 API 返回 401，提示用户 API Key 可能失效，引导重新配置

---

## Gotchas

- ⚠️ **不要每次都问 API Key**：脚本自动从 `~/.agnes/config.json` 读取，已配置就直接用；仅在未配置或 401 时才引导设置
- ⚠️ **图像 `response_format` 必须放在 `extra_body` 中**：放顶层会报 400 错误
- ⚠️ **图生图的输入图片放在顶层 `image` 数组**，不是 `extra_body.image`
- ⚠️ **图生图不需要 `tags: ["img2img"]`**
- ⚠️ **视频 `num_frames` 必须 ≤ 441 且满足 8n+1**（如 81/121/161/241/441）
- ⚠️ **视频是异步任务**：创建后需要轮询，建议间隔 5 秒
- ⚠️ **视频 URL 在 `remixed_from_video_id` 字段**，不是 `video_url`
- ⚠️ **图像输入 URL 必须公网可访问**：如无法公网访问，使用本地文件路径（脚本自动转 Base64）
- ⚠️ **不要将 API Key 提交到版本控制**

---

## 错误处理

| 状态码 | 原因 | 处理方式 |
|--------|------|----------|
| 400 | 请求参数无效 | 检查参数格式，特别关注 `response_format` 位置 |
| 401 | API Key 无效或失效 | 提示用户 Key 可能失效，引导重新配置：`agnes_config.py set --api-key NEW_KEY` |
| 404 | 任务或视频不存在 | 确认 video_id 或 task_id 是否正确 |
| 500 | 服务器错误 | 稍后重试 |
| 503 | 服务繁忙 | 等待后重试 |

---

## 参考文档

- `references/agnes-image-api.md` — Agnes Image 2.1 Flash API 完整文档
- `references/agnes-video-api.md` — Agnes Video V2.0 API 完整文档

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fuzhengwei](https://github.com/fuzhengwei)
- **Source:** [fuzhengwei/xfg-skills-agnes](https://github.com/fuzhengwei/xfg-skills-agnes)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fuzhengwei-xfg-skills-agnes-xfg-skills-agnes
- Seller: https://agentstack.voostack.com/s/fuzhengwei
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.