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 IntentModelEndpointGenerate images from text (high info density preferred)agnes-image-2.1-flash``POST /v1/images/generationsEdit/existing image, image-to-image, multi-image compositionagnes-image-2.0-flash``POST /v1/images/generationsGenerate videos, clips, animationsagnes-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:

bash

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):

bash

# 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:

bash

# 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#

ParameterDescriptionDefaultpromptText description of the desired image (required)—sizeImage dimensions. Supported: 1024x1024, 1792x1024, 1024x1792``1024x1024``nNumber of images to generate1``extra_body.imageInput image URL(s) for image-to-image or multi-image tasks—tagsTask type tag, e.g. ["img2img"] for image-to-image—

Recommended Prompt Structure#

text

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

Example:

text

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:

text

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:

json

{
  "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`):

bash

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

Or call the API directly with curl:

bash

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#

ParameterDescriptionDefaultpromptText description of the desired video (required)—durationVideo duration in seconds5

Response Handling#

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

json

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

Poll for completion:

bash

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