Agnes Ai

Generate images or videos via Agnes AI API using user-provided prompts, handling API key setup, file download, and asynchronous video status polling.

name: agnes-ai description: Wraps the Agnes AI API for image and video generation. Use when the user asks to generate images, pictures, photos, or videos with Agnes AI. Two image models: agnes-image-2.0-flash (image-to-image, multi-image) and agnes-image-2.1-flash (high-density text-to-image). OpenAI-compatible protocol. Requires an API key provided on first use.

Agnes AI — Image & Video Generation

Overview

Agnes AI provides image and video generation models accessible through an OpenAI-compatible HTTP API. Use this skill whenever the user wants to generate images or videos with Agnes AI.

• API Base URL: https://apihub.agnes-ai.com/v1
• Auth: Bearer token (AGNES_API_KEY)
• Protocol: OpenAI-compatible request/response format

Model Selection

User Intent	Model	Endpoint
Generate images from text (high info density preferred)	agnes-image-2.1-flash	POST /v1/images/generations
Edit/existing image, image-to-image, multi-image composition	agnes-image-2.0-flash	POST /v1/images/generations
Generate videos, clips, animations	agnes-video-v2.0	POST /v1/video/generations

Model choice guidance:

• Default to agnes-image-2.1-flash for text-to-image (better high-information-density output)
• Use agnes-image-2.0-flash when the user provides an input image for editing, style transfer, or multi-image composition
• If unsure, ask the user which model they prefer, or default to agnes-image-2.1-flash for text-to-image

API Key Setup

IMPORTANT: Before any image or video generation, you MUST check for the API key. Do NOT proceed to call the API without a valid key. This check happens the first time the user asks you to generate something with Agnes (not during skill installation).

Checking for the Key

When the skill is triggered (user asks to generate an image/video), check these locations in order:

1. Environment variable AGNES_API_KEY
2. File ~/.agnes-ai/api_key

If No Key Found

Immediately stop and ask the user:

要使用 Agnes AI 生成功能，需要先配置 API Key。请提供你的 Agnes AI API Key，我会安全存储在本地。 （获取方式：登录 https://apihub.agnes-ai.com 后在控制台查看）

Do NOT attempt to call the API without a key.

Saving the Key

Save the key the user provides by writing it to ~/.agnes-ai/api_key (plain text, no trailing newline). Then set the environment variable for the current session:

mkdir -p ~/.agnes-ai
echo -n "sk-your-key-here" > ~/.agnes-ai/api_key
export AGNES_API_KEY="sk-your-key-here"

After saving, proceed with the generation request.

Never echo or log the API key value in any user-visible output.

Image Generation

Trigger: user asks to generate / create / make an image, picture, photo, illustration, poster, or visual with Agnes.

Model Selection Logic

1. If the user provides an input image (image-to-image, editing, style transfer) → use agnes-image-2.0-flash
2. If the user wants multi-image composition → use agnes-image-2.0-flash
3. Default (text-to-image) → use agnes-image-2.1-flash

Call the API

Use the bundled script (scripts/generate.py in the same directory as this SKILL.md) for reliable execution. The script requires Python3 (standard library only, no dependencies):

# Text-to-image (agnes-image-2.1-flash, default)
python3 scripts/generate.py image \
  --prompt "<prompt>" \
  --size "<size>" \
  --output "<output_path>"

# Image-to-image (agnes-image-2.0-flash)
python3 scripts/generate.py image \
  --prompt "<prompt>" \
  --image "<input_image_url_or_path>" \
  --size "<size>" \
  --output "<output_path>"

# Multi-image composition (agnes-image-2.0-flash)
python3 scripts/generate.py image \
  --prompt "<prompt>" \
  --image "url1" "url2" \
  --size "<size>" \
  --output "<output_path>"

Or call the API directly with curl:

# Text-to-image (agnes-image-2.1-flash)
curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "<prompt>",
    "size": "<size>"
  }'

# Image-to-image (agnes-image-2.0-flash)
curl -s -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.0-flash",
    "tags": ["img2img"],
    "prompt": "<prompt>",
    "size": "<size>",
    "extra_body": {
      "image": ["<input_image_url>"],
      "response_format": "url"
    }
  }'

Parameters

Parameter	Description	Default
prompt	Text description of the desired image (required)	—
size	Image dimensions. Supported: 1024x1024, 1792x1024, 1024x1792	1024x1024
n	Number of images to generate	1
extra_body.image	Input image URL(s) for image-to-image or multi-image tasks	—
tags	Task type tag, e.g. ["img2img"] for image-to-image	—

Recommended Prompt Structure

[Subject] + [Scene / Environment] + [Style] + [Lighting] + [Composition] + [Quality Requirements]

Example:

A luminous floating city above a misty canyon at sunrise, cinematic realism, wide-angle composition, rich architectural details, soft golden light, high visual density

For image-to-image, also describe what to change AND what to preserve:

Transform the scene into a rain-soaked cyberpunk night with neon reflections while preserving the original composition and main subject layout.

Response Handling

The API returns an OpenAI-compatible response:

{
  "data": [
    {
      "url": "https://..."
    }
  ],
  "usage": {
    "generated_images": 1
  }
}

The url field contains a temporary download link. Download the image with curl or wget and save locally. If b64_json is present, decode it with base64 -d to get the raw image bytes.

After saving the image file locally, deliver it to the user — display a preview if your platform supports it, or attach the file to your response. Tell the user where the file was saved.

Video Generation

Trigger: user asks to generate / create / make a video, clip, animation, or motion content with Agnes.

Call the API

Use the bundled script (scripts/generate.py in the same directory as this SKILL.md`):

python3 scripts/generate.py video \
  --prompt "<prompt>" \
  --duration <seconds> \
  --output "<output_path>"

Or call the API directly with curl:

curl -s -X POST "https://apihub.agnes-ai.com/v1/video/generations" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "<prompt>",
    "duration": <seconds>
  }'

Parameters

Parameter	Description	Default
prompt	Text description of the desired video (required)	—
duration	Video duration in seconds	5

Response Handling

Video generation is asynchronous. The API returns a task ID:

{
  "id": "task_abc123",
  "status": "processing"
}

Poll for completion:

curl -s "https://apihub.agnes-ai.com/v1/video/generations/<task_id>" \
  -H "Authorization: Bearer $AGNES_API_KEY"

When status becomes completed, the response contains a url or output field with the video download link. Download it and deliver to the user.

The bundled scripts/generate.py script handles polling automatically — prefer using it over raw curl.

Supported Image Sizes

• 1024x1024 — square (default)
• 1792x1024 — landscape
• 1024x1792 — portrait

Error Handling

If the API returns a non-200 status:

1. Check that the API key is valid and has not expired
2. Verify the prompt is not empty and does not violate content policy
3. If the error persists, tell the user the error message and suggest checking their Agnes AI dashboard

After Generation

After successfully generating and saving an image or video file:

1. Tell the user the file path and deliver/attach the file to them
2. For images: show a preview or display the file if your platform supports inline rendering
3. For videos: provide a way for the user to view or download the file