Agnes AI image and video generation skill. Fully self-contained and ready for direct distribution.
Features:
- Text-to-image / image-to-image (using the Agnes Image API)
- Text-to-video / image-to-video (using the Agnes Video API)
- Convert local images to public URLs (built-in HTTP server + Cloudflare tunnel)
Quick Start
1. Configure the API Key
Copy config.example.json to config.json, and enter your API Key:
{
"agnes_api": {
"image_api_key": "你的图片 API Key",
"video_api_key": "你的视频 API Key"
},
"output": {
"directory": "输出目录路径"
}
}
Get an API Key: Register at https://platform.agnes-ai.com,在 Dashboard to create a Key.
2. Basic Usage
Text-to-image:
用户:帮我生成一张图片:一只橘猫坐在窗台上,阳光洒进来
Image-to-image (local image):
用户:把 /path/to/local/image.png 的背景改成海边
Text-to-video:
用户:生成一个老虎追逐鹿的视频,5秒,电影级镜头
Image-to-video (local image):
用户:用 /path/to/image.png 作为首帧,生成人物转身看向镜头的视频
Convert local images to URLs (built-in Bridge)
This skill has a built-in bridge consisting of a local HTTP server + Cloudflare tunnel, with no dependency on external image hosting services.
How It Works
- Local HTTP server: starts an asset server at 127.0.0.1:8787
- Cloudflare tunnel: creates a publicly accessible URL via cloudflared
- Asset registration: local files are registered with the server, generating a temporary access token
Automatic startup
When a local image needs to be converted, the bridge starts automatically:
用户:把 /Users/xxx/Desktop/photo.png 转成公网 URL
The Assistant will call the built-in bridge, which automatically:
- Checks whether cloudflared is installed (on macOS it is installed automatically via Homebrew)
- Starts the local asset server
- Starts the Cloudflare tunnel
- Registers the file and returns a public URL
Manually Manage the Bridge
# 进入 bridge 目录
cd bridge
# 确保 bridge 运行(自动启动服务器 + 隧道)
node bin/agnes-bridge.js ensure
# 查看状态
node bin/agnes-bridge.js status
# 停止 bridge
node bin/agnes-bridge.js stop
# 清理过期资产
node bin/agnes-bridge.js cleanup
# 检查依赖
node bin/agnes-bridge.js doctor
Environment Variables
| Variable | Description | Default Value |
|---|---|---|
AGNES_BRIDGE_STATE_DIR |
State storage directory | ~/.agnes-local-bridge |
AGNES_BRIDGE_PORT |
Local server port | 8787 |
AGNES_PUBLIC_BASE_URL |
Manually specify the public URL | Automatically obtained |
AGNES_ASSET_TTL_SECONDS |
Asset validity period (seconds) | 3600 |
AGNES_BRIDGE_IDLE_SECONDS |
Daemon idle timeout (seconds) | 3600 |
Dependency Requirements
- Node.js >= 20(pure JS, no external dependencies)
- cloudflared(installed automatically via Homebrew on macOS; manual installation required on other platforms)
Install cloudflared:
- macOS:
brew install cloudflared - Windows:
winget install --id Cloudflare.cloudflared --exact - Linux:
sudo apt install cloudflaredor download from the official website
Image Generation
API Endpoint
POST https://apihub.agnes-ai.com/v1/images/generations
Request Parameters
| Parameter | Type | Description |
|---|---|---|
model |
string | Model:agnes-image-2.1-flash |
prompt |
string | Image description (required) |
size |
string | Size:1024x1024 etc. |
n |
int | Number to generate (default 1) |
quality |
string | standard/hd/low |
output_format |
string | png/webp/jpeg |
background |
string | transparent(transparent background) |
extra_body |
object | Image-to-image configuration |
extra_body.image |
array | Array of input image URLs (image-to-image) |
Text-to-image
{
"model": "agnes-image-2.1-flash",
"prompt": "A futuristic cityscape at sunset",
"size": "1024x1024"
}
Correct usage for image-to-image
Use the extra_body.image array:
{
"model": "agnes-image-2.1-flash",
"prompt": "Transform the scene into a rain-soaked cyberpunk night",
"size": "1024x768",
"extra_body": {
"image": [
"https://example.com/input-image.png"
],
"response_format": "url"
}
}
Supported sizes
1024x1024 | 1792x1024 | 1024x1792 | 1024x768 | 768x1024 | 512x512 | 256x256
Response Format
{
"created": 1234567890,
"data": [
{
"url": "https://cdn.agnes-ai.com/xxx.png"
}
]
}
See for detailed parameters agnes-image.md。
Video Generation
API Endpoint
POST https://apihub.agnes-ai.com/v1/videos
GET https://apihub.agnes-ai.com/v1/videos/{task_id}
Request Parameters
| Parameter | Type | Description |
|---|---|---|
model |
string | agnes-video-v2.0(required) |
prompt |
string | Video description (required) |
image |
string | Input image URL (single-image video generation) |
num_frames |
int | Frame count (must satisfy 8n+1) |
frame_rate |
int | Frame rate (default 24) |
height |
int | Height (default 768) |
width |
int | Width (default 1152) |
extra_body |
object | Multi-image/keyframe configuration |
extra_body.image |
array | Multi-image URL array |
extra_body.mode |
string | keyframes Keyframe mode |
Correct usage of image-to-video
Single-image video generation(use image field):
{
"model": "agnes-video-v2.0",
"prompt": "The woman slowly turns around and looks back at the camera",
"image": "https://example.com/image.png",
"num_frames": 121,
"frame_rate": 24
}
Multi-image video generation(use extra_body.image):
{
"model": "agnes-video-v2.0",
"prompt": "Create a smooth transformation scene",
"extra_body": {
"image": [
"https://example.com/image1.png",
"https://example.com/image2.png"
]
},
"num_frames": 121,
"frame_rate": 24
}
Keyframe animation(use extra_body.mode: "keyframes"):
{
"model": "agnes-video-v2.0",
"prompt": "Generate a smooth cinematic transition",
"extra_body": {
"image": [
"https://example.com/keyframe1.png",
"https://example.com/keyframe2.png"
],
"mode": "keyframes"
},
"num_frames": 121,
"frame_rate": 24
}
Frame count constraint
num_frames must satisfy 8n + 1 format. Valid values:
| Frame count | Duration (@24fps) |
|---|---|
| 81 | ~3.4 seconds |
| 121 | ~5 seconds |
| 161 | ~6.7 seconds |
| 241 | ~10 seconds |
| 441 | ~18.4 seconds |
Asynchronous polling
Video generation is asynchronous and requires polling to get the result:
// 创建任务响应
{
"id": "task_xxx",
"object": "video",
"model": "agnes-video-v2.0",
"status": "queued",
"progress": 0,
"created_at": 1234567890
}
// 轮询响应(完成后)
{
"id": "task_xxx",
"object": "video",
"model": "agnes-video-v2.0",
"status": "completed",
"progress": 100,
"video_url": "https://storage.googleapis.com/xxx.mp4",
"size": "1152x768",
"seconds": "5.0"
}
Note: the video URL is in the video_url field!
See agnes-video.md。
Prompt best practices
Image prompts
Describe clearly, including subject, scene, and style:
一只橘猫坐在窗台上,阳光洒进来,温暖治愈,水彩画风格
Video prompts
Include subject, action, scene, camera, and lighting:
[主体] + [动作] + [场景] + [镜头运动] + [光影] + [风格]
示例:老虎追逐鹿穿过茂密森林,动态跟拍镜头,尘土飞扬,戏剧性光影,野生动物纪录片风格
Error handling
| Error | Solution |
|---|---|
| Invalid API Key | Check whether the Key is correct and whether it has expired |
| cloudflared is not installed | macOS will install it automatically; other platforms require manual installation |
| Tunnel failed to start | Check the network, or manually set AGNES_PUBLIC_BASE_URL |
| Video generation timed out | Increase the polling wait time |
| Invalid num_frames | Use valid values: 81/121/161/241/441 |
| URL validation failed | Check whether the image URL is accessible |
Detailed documentation
When more parameter descriptions are needed, read:
agnes-image.md— Detailed parameters for the image APIagnes-video.md— Detailed parameters for the video API
Distribution instructions
This skill is fully self-contained and the entire directory can be copied directly for distribution:
yufan-Agnes/
├── SKILL.md # 主文档
├── config.example.json # 配置示例
├── agnes-image.md # 图片 API 详细参数
├── agnes-video.md # 视频 API 详细参数
└── bridge/ # 内置本地图片转 URL bridge
├── package.json
├── bin/
│ └── agnes-bridge.js
└── src/
├── cli.js
├── config.js
├── state.js
├── assets.js
├── server.js
├── tunnel.js
├── daemon.js
├── deps.js
└── media.js
Users only need to:
- Copy
config.example.jsonasconfig.json - Fill in the API Key
- Ensure Node.js >= 20 and cloudflared are installed
- Use the skill