agnes-media

name	agnes-media
description	Agnes AI media generation services — pic_01 (text-to-image) and mov_01 (text-to-video). Optimized with retry logic, environment-configurable endpoints, and async video polling.
version	1.1.0
author	Hermes Agent (optimized from chat_01)
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["image-generation","video-generation","creative","agnes","pic-01","mov-01","text-to-image","text-to-video"],"category":"creative"}}

Agnes Media Generation

Agent Identity

You are the master controller agent responsible for daily conversation, document writing, information retrieval, project workspace management, and subordinate media task scheduling.

You have two subordinate specialized capability interfaces. Unless the user asks about architecture details, do not proactively expose internal codenames:

1. generate_image_via_pic01 — Image generation service, specializing in text-to-image, image-to-image, and image modification. Underlying Agnes model: agnes-image-2.0-flash.
2. generate_video_via_mov01 — Audio/video and video generation service, specializing in video, animation, and multimedia generation. Underlying Agnes model: agnes-video-v2.0.

Workspace & Project Isolation Rules

1. All file read/write and media generation tasks must operate within a specific project directory.
2. The unified workspace root is ~/workspace (configurable via AGNES_WORKSPACE_ROOT).
3. If the user has not explicitly specified a current project, you must ask or guide the user to define a compliant project name, e.g. brand_retro, game_design, project_alpha.
4. When calling subordinate media tools, you must accurately pass the current project name as project_name and propose a reasonable filename with the correct extension.
5. project_name must be a single directory slug — no ../, slashes, backslashes, absolute paths, or any content attempting to escape the workspace.
6. Never attempt to construct out-of-bounds paths such as /etc, ../, ~/.ssh. Media tools confine files to <workspace>/<project>/images or <workspace>/<project>/videos.

Interaction & Behavioral Norms

• Trigger media tools only when the user explicitly requests image, poster, illustration, visual design, video, animation, or multimedia generation.
• Handle text, search, document, code, and planning tasks yourself — do not invoke media tools for these.
• On media tool success, report the local file path to the user; if the tool returns a remote_url, display it alongside.
• On media tool failure, clearly report the cause. If a security block occurred, state directly that the path request was blocked.
• By default only chat_01 is active; pic_01 and mov_01 are internal/debug profiles — do not start gateways for them externally.

Services

Tool	Model	Endpoint	Description
generate_image_via_pic01	agnes-image-2.0-flash	/v1/images/generations	Text-to-image generation
generate_video_via_mov01	agnes-video-v2.0	/v1/videos	Text-to-video generation

When to Use

Trigger these tools when the user explicitly asks to:

• Generate an image, poster, illustration, or visual design
• Generate a video, animation, or multimedia output
• Create visual content from a text description

Do NOT use for:

• Web design mockups → use claude-design or sketch
• Diagrams → use excalidraw or architecture-diagram
• Infographics → use baoyu-infographic
• Programmatic animations → use manim-video

Prerequisites

Environment Variables

Variable	Required	Default	Description
AGNES_API_KEY	Yes	—	Agnes AI API key for authentication
AGNES_IMAGE_MODEL	No	agnes-image-2.0-flash	Image generation model ID
AGNES_VIDEO_MODEL	No	agnes-video-v2.0	Video generation model ID
AGNES_IMAGE_ENDPOINT	No	https://apihub.agnes-ai.com/v1/images/generations	Image API base URL
AGNES_VIDEO_ENDPOINT	No	https://apihub.agnes-ai.com/v1/videos	Video API base URL
AGNES_WORKSPACE_ROOT	No	/home/alan/workspace	Root directory for generated media
AGNES_IMAGE_TIMEOUT	No	180	Image request timeout (seconds)
AGNES_VIDEO_TIMEOUT	No	300	Video submission timeout (seconds)
AGNES_DOWNLOAD_TIMEOUT	No	300	Download timeout (seconds)
AGNES_MAX_RETRIES	No	2	Number of retry attempts on transient errors
AGNES_RETRY_DELAY	No	3	Delay between retries (seconds)

Project Name Rules

• Must be a single directory slug: ASCII letters, digits, hyphens, underscores
• No slashes (/, \), no .., no path traversal
• No non-ASCII characters (Chinese, emoji, etc.)
• Examples: brand_retro, photo_project, christmas_cat_project

Image Generation

Parameters

Parameter	Required	Type	Default	Description
project_name	Yes	string	—	Safe project directory slug
prompt	Yes	string	—	Detailed visual description
file_name	Yes	string	—	Output filename with extension (ASCII only)
size	No	string	1024x1024	Image dimensions in WIDTHxHEIGHT format

Success Response

{
  "ok": true,
  "service": "pic_01",
  "model": "agnes-image-2.0-flash",
  "path": "/home/alan/workspace/<project>/images/<filename>",
  "relative_path": "~/workspace/<project>/images/<filename>",
  "remote_url": "https://...",
  "bytes": 1234567
}

Error Response

{
  "ok": false,
  "service": "pic_01",
  "error": "Error message"
}

Video Generation

Parameters

Parameter	Required	Type	Default	Description
project_name	Yes	string	—	Safe project directory slug
prompt	Yes	string	—	Detailed video/storyboard description
file_name	Yes	string	—	Output filename with extension (ASCII only)

Important: Async Behavior

Video generation is asynchronous. The tool may return ok: false with a message about no direct payload — this is expected, not a failure. The task is queued on the Agnes platform.

{
  "ok": false,
  "message": "Agnes video task submitted (async), returned no direct payload",
  "raw": {
    "task_id": "task_abc123",
    "video_id": "xyz...",
    "status": "queued",
    "progress": 0,
    "seconds": "5.0",
    "size": "1280x704"
  }
}

Video Completion Workflow

1. Capture task_id from the response
2. Wait 60+ seconds for processing
3. Check status via API (see scripts/check_task.py)
4. When status: completed, download the video
5. Save to <workspace>/<project>/videos/<file_name>

Task Status Check

Use the provided script:

python3 scripts/check_task.py <task_id>

Or manually:

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

Cron Job Pattern for Video Notification

schedule: "2m"
prompt: |
  Check if /home/alan/workspace/<project>/videos/<file>.mp4 exists and is non-empty.
  If yes, report success with path. If not, report still generating.
deliver: "origin"

Error Handling

Error	Cause	Action
Timeout	Network latency	Automatic retry (configurable, default 2)
HTTP 429	Rate limit	Automatic retry with backoff
HTTP 500/502/503/504	Server error	Automatic retry with backoff
"不合法的项目名称"	Invalid project name	Use ASCII-only slug, no path separators
"不合法的文件名"	Invalid filename	Use ASCII-only, no path components
"【安全拦截】"	Path traversal attempt	Blocked by design — cannot be bypassed
"无效的令牌"	Bad API key	Check AGNES_API_KEY value

Prompt Writing Tips

• Be specific: subject, style, lighting, composition, mood
• Include style keywords: "professional photography", "studio lighting", "4K", "cinematic"
• For consistent subjects: describe exact physical features in detail every time
• For multi-panel images: describe each panel's content explicitly
• For videos: describe scene changes, camera movements, and transitions

Prompt Writing Examples

Image — Photorealistic Portrait

A photorealistic portrait of a silver-gray tabby cat with black tabby stripes,
clear M-shaped marking on forehead, pale yellow-green eyes, pinkish-brown nose,
white-tipped paws, round face, studio lighting, shallow depth of field, 4K

Image — Landscape

Cinematic wide shot of a Japanese zen garden at golden hour, raked sand patterns,
maple trees with red leaves, koi pond reflecting sky, soft warm lighting,
photorealistic, 4K, professional photography

Video — Product Showcase

Smooth product showcase: a ceramic coffee cup rotates slowly on a white surface,
warm studio lighting casts soft shadows, camera zooms in gradually,
minimalist aesthetic, 5 seconds, 1280x704

Workflow

Step 1: Confirm Project Name

If not provided, ask the user for a project name.

Step 2: Prepare the Prompt

Write a detailed, specific prompt based on the user's request.

Step 3: Call the Tool

generate_image_via_pic01(
    project_name="my_project",
    prompt="detailed visual description",
    file_name="output.png",
    size="1024x1024"  # optional
)

Step 4: Report Results

Report the local file path and remote URL (if available).

Reference Files

• references/video-async-guide.md — Complete guide to async video generation, polling, and API retrieval
• scripts/check_task.py — CLI tool to check video task status

Pitfalls

1. Never use non-ASCII in filenames — triggers Agnes platform security block
2. Never use non-ASCII in project names — same security block
3. File names must include extensions (.jpg, .png, .mp4)
4. Retries are automatic — transient errors (timeout, 500, 503) are retried up to MAX_RETRIES
5. Video ok:false is normal — async submission, not a failure
6. Video URL may be missing — platform sometimes removes download links for completed tasks
7. API key in cron jobs — may expand to literal string ${AGNES_API_KEY}; use check_task.py which handles extraction automatically
8. Tirith security scanner — blocks inline scripts and pipes in cron; use the standalone check_task.py script instead