Agnes-AI

Agnes-AI

English | 中文说明

A unified Python CLI for Agnes AI models — text generation, image understanding, image generation, and video generation, all with zero external dependencies.

Built by AI Lab. This repo wraps every Agnes API endpoint into a single agnes.py with sensible defaults, auto-translation, and dry-run validation — no pip install required.

What's inside:

scripts/agnes.py   →  CLI (text, image understanding, image, video)
SKILL.md           →  Agent skill for AI coding assistants
examples/server.py →  Web playground at http://localhost:8888

Why use this?

• Zero dependencies — Python stdlib only, works out of the box
• Agent-ready — ships with SKILL.md and playground for testing
• Auto-translate — write prompts in any language
• Dry-run mode — validate before spending credits
• Smart defaults — sizes, frame counts, polling — all pre-configured
• Free to use — no GPU needed, just an API key

Overview

• Text generation — chat, tool calling, streaming with agnes-3.0-flash
• Image understanding — describe images with agnes-3.0-flash multimodal
• Image generation — text2img, img2img, multi-image compose with agnes-image-2.5-flash
• Video generation — text2video, img2video, keyframe animation with agnes-video-2.5-flash
• Auto-translate — non-English prompts translated to English automatically
• Zero dependencies — Python stdlib only, no pip install required

Installation

Requires Python 3.8+ and an Agnes AI API key.

# Clone the repository
git clone https://github.com/1038lab/Agnes-AI.git
cd Agnes-AI

# Optionally add scripts to your PATH
export PATH="$PWD/scripts:$PATH"

Getting an API Key

1. Sign up at https://apihub.agnes-ai.com
2. Go to API Keys in your dashboard
3. Click Create API Key and copy the sk-... key

Quick Start

# Set your API key
export AGNES_API_KEY="your-key-here"

# Or use the interactive setup
python scripts/agnes.py setup

# Generate text
python scripts/agnes.py text --prompt "Hello, introduce yourself"

# Describe an image
python scripts/agnes.py text --prompt "Describe this image in detail" --image-url photo.jpg

# Generate an image
python scripts/agnes.py image text2img --prompt "A cat wearing a spacesuit, digital art"

# Generate a video
python scripts/agnes.py video text2video --prompt "Ocean waves at sunset, cinematic quality" --seconds 5

CLI Reference

Global Options

Option	Description
--dry-run	Print request body without calling the API
--no-translate	Disable automatic prompt translation
--verbose	Print debug info to stderr

agnes setup

Save your API key to your shell profile (~/.zshrc / ~/.bashrc / ~/.profile).

agnes setup

agnes text

Text generation, chat completions, and image understanding (multimodal).

agnes text --prompt "Write a poem about artificial intelligence"
agnes text --prompt "Describe this image in detail" --image-url photo.jpg
agnes text --system "Analyze the art style" --image-url painting.png
agnes text --prompt "Write a sorting algorithm in Python" --system "You are a senior engineer"
agnes text --prompt "Tell me a joke" --stream
agnes text --prompt "History of computing" --temperature 0.9 --max-tokens 2048
agnes text --prompt "What is 1+1?" --message "user: What is 2+2?" --message "assistant: 4"

Argument	Description
--prompt	Prompt text (optional with --image-url)
--image-url	Image file path or URL for multimodal understanding
--system	System prompt
--message	Multi-turn messages (repeatable, format role: content)
--stream	Enable streaming output
--temperature	Sampling temperature (default 0.7)
--top-p	Top-p sampling (default 0.9)
--max-tokens	Max output tokens (default 4096)
--tools-json	Tool definitions as JSON
--tool-choice	Tool selection strategy
--json-output	Output as JSON
--model	Model name (default agnes-3.0-flash)

agnes image

Image generation.

# Text-to-image
agnes image text2img --prompt "Cyberpunk city at night"

# Image-to-image
agnes image img2img --prompt "Make it look like a watercolor" --image-url https://example.com/photo.jpg

# Compose multiple images
agnes image compose --prompt "Blend these images"   --image-url https://example.com/img1.jpg   --image-url https://example.com/img2.jpg

# Custom size and download directory
agnes image text2img --prompt "An oil painting" --size "1816x1024" --output-dir ./output

Argument	Description
mode	Mode: text2img / img2img / compose (required)
--prompt	Prompt text (required)
--image-url	Reference image URL(s), repeatable
--size	Image dimensions (default 1024x768)
--output-dir	Download directory (omit to print URLs only)
--model	Model name (default agnes-image-2.5-flash)

agnes video

Video generation with automatic polling and optional download.

# Text-to-video (modern 2.5-flash with seconds duration, auto-poll)
agnes video text2video --prompt "A butterfly flying through a flower field" --seconds 5

# Image-to-video
agnes video img2video --prompt "Animate this image" --image-url https://example.com/photo.jpg --seconds 5

# Keyframe video (start and end frames)
agnes video keyframes --prompt "Animation sequence"   --image-url https://example.com/frame1.jpg   --image-url https://example.com/frame2.jpg --seconds 6

# Modern aspect ratio and resolution (Flash 720P)
agnes video text2video --prompt "Waterfall"   --seconds 6 --aspect-ratio 16:9 --size 720P   --download --output-dir ./videos

# Legacy frame-count mode (agnes-video-v2.0)
agnes video text2video --prompt "Ocean waves" --model agnes-video-v2.0   --width 1920 --height 1080 --num-frames 241 --frame-rate 30

# Disable polling, just get the task_id
agnes video text2video --prompt "Sunset" --no-poll

https://github.com/user-attachments/assets/25af3d70-c242-4c10-9320-6107f23b9320

Argument	Description
mode	Mode: text2video / img2video / keyframes / reference (required)
--prompt	Prompt text (required)
--image-url	Reference image URL(s), repeatable
--audio-url	Reference audio URL(s), repeatable
--ref-video-url	Reference video URL(s), repeatable
--model	Video model (default agnes-video-2.5-flash, or agnes-video-2.5, agnes-video-v2.0)
--seconds	Duration in seconds (default 5, range 4–12)
--aspect-ratio	Aspect ratio (default 16:9, choices: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9)
--size	Resolution (default 720P, choices: 720P, 1080P, 1K, 2K)
--width	Video width in pixels (legacy v2.0)
--height	Video height in pixels (legacy v2.0)
--num-frames	Number of frames (legacy v2.0, default 121, must satisfy 8n+1, max 441)
--frame-rate	Frames per second (legacy v2.0, default 24, range 1–60)
--seed	Random seed for reproducibility
--num-inference-steps	Number of denoising steps (legacy v2.0)
--negative-prompt	Things to avoid in the video (legacy v2.0)
--no-poll	Disable automatic polling
--poll-interval	Poll interval in seconds (default 5)
--timeout	Timeout in seconds (default 900)
--download	Download video after completion
--output-dir	Output directory

agnes poll

Poll for video generation status.

agnes poll VIDEO_ID
agnes poll VIDEO_ID --poll-interval 5 --timeout 600
agnes poll VIDEO_ID --download --output-dir ./videos

agnes smoke-test

Run end-to-end smoke tests in dry-run mode (no API calls).

agnes smoke-test
agnes smoke-test --video-case text2video

Features

Auto-Translation

When a prompt contains non-ASCII characters, agnes automatically translates it to English using agnes-3.0-flash before sending it to the target model. Use --no-translate to disable.

# Auto-translate (default)
agnes image text2img --prompt "一只橘猫在窗台上晒太阳"

# Equivalent to manually translating then:
agnes image text2img --prompt "An orange cat basking in the sun on a windowsill" --no-translate

Automatic Media Upload

For img2img, compose, img2video, and keyframes modes, you can pass local file paths to --image-url. The tool will automatically upload the file to Litterbox and use the public URL.

agnes image img2img --prompt "Make it cartoon style" --image-url ./my-photo.jpg
agnes video keyframes --prompt "Scene transition" --image-url ./start.png --image-url ./end.png

Video Auto-Polling

Video generation polls for completion by default with real-time rendering progress updates (0% to 100%). Pass --download to save the result locally.

Dry-Run Mode

Use --dry-run to inspect the request payload without calling the API:

agnes image text2img --prompt "test" --dry-run
agnes video text2video --prompt "test" --dry-run

Usage Limits

Plan	Price	Limits
Free Access	$0	Fair-use quota (no hard cap), basic TPS limit
Starter	$2/mo	1500 requests per 5 hours, higher RPM
Plus	$5/mo	7500 requests per 5 hours, higher RPM
Pro	$25/mo	30000 requests per 5 hours, higher RPM

See Common Error Codes for API error descriptions.

Changelog

Date	Changes
2026-09-15	Upgraded default models to next-gen Agnes AI: agnes-3.0-flash, agnes-image-2.5-flash, agnes-video-2.5-flash; added modern video generation (--seconds, --aspect-ratio, --size), real-time rendering progress bar, Flash 720P safeguard, and multi-modal reference support while preserving full legacy v2.0 compatibility
2026-07-09	Added image understanding (multimodal describe); new Describe Image sub-mode in Playground Text tab; CLI preview placeholders use {image} (avoids innerHTML tag-eating); fixed centered text in result area; README rewrite, renamed to Agnes-AI, detailed API key guide, AILab credit
2026-07	Fixed Image API format: img2img/compose image field moved to top level (not inside extra_body); Playground size selection redesigned with ratio/resolution/duration (Pavo AI style); Playground result area fixed (max-width, height auto, no flex); Image timeout 120s → 300s; text.py resp.read() moved inside try block

Zero-Dependency Philosophy

The entire project uses only Python standard library modules — no pip install required:

• urllib.request — HTTP requests
• argparse — CLI argument parsing
• json — serialization
• os, sys, time, mimetypes — system utilities
• re — string processing (setup command)

Interactive Playground

A web UI for all features — no terminal needed:

# One-click launch
open examples/start.command

# Or manually
python3 examples/server.py

Open http://localhost:8888 to use:

• Text — chat / streaming / JSON output / image description
• Image — text2img / img2img / compose, all sizes with ratio labels
• Video — text2video / img2video / start & end frames, with FPS and duration preview

Project Structure

Agnes-AI/
├── scripts/          # Core Python modules
│   ├── agnes.py      # CLI entry point and dispatch
│   ├── text.py       # Text generation
│   ├── image.py      # Image generation
│   ├── video.py      # Video generation + polling
│   ├── translate.py  # Auto-translation
│   └── media.py      # Media upload and download
├── references/       # API reference + error codes
├── examples/         # Playground web UI + server
├── tests/            # Smoke tests (no framework needed)
└── agents/           # Agent configuration files

Environment Variables

Variable	Description
AGNES_API_KEY	Primary API key
AGNES_API_TOKEN	Fallback API key
APIHUB_AGNES_API_KEY	Fallback API key
AGNES_API_BASE	API base URL (default https://apihub.agnes-ai.com)

License

GNU General Public License v3.0. See LICENSE.

Links

• API Reference
• Error Codes
• Agnes AI
• API Hub
• ComfyUI-Agnes-AI — ComfyUI custom nodes built on this toolkit