SuperAPI AI Directory

yufan-Agnes

Coding & development

View repository

Updated 10-15 21:39

About this skill

yufan-Agnes

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

  1. Local HTTP server: starts an asset server at 127.0.0.1:8787
  2. Cloudflare tunnel: creates a publicly accessible URL via cloudflared
  3. 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:

  1. Checks whether cloudflared is installed (on macOS it is installed automatically via Homebrew)
  2. Starts the local asset server
  3. Starts the Cloudflare tunnel
  4. 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 cloudflared or 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 API
  • agnes-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:

  1. Copy config.example.json as config.json
  2. Fill in the API Key
  3. Ensure Node.js >= 20 and cloudflared are installed
  4. Use the skill