{"id":"91419254-fa67-4df6-9771-0cb468054702","slug":"agnes-ai","kind":"skill","name":"Agnes-AI","summary":"A unified Python CLI for Agnes AI models — text generation, image understanding, image generation, and video generation, all with zero external dependencies.","owner":"1038lab","repoUrl":"https://github.com/1038lab/Agnes-AI","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":4,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-07-09T07:57:51.000Z","addedAt":"2026-10-21T23:26:07.893Z","logoUrl":"https://avatars.githubusercontent.com/u/129358391?u=8a385dc43e456cfa1e50fc6c8d77871518386169&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T09:51:34.764Z","sample":false,"url":"https://conduits.dev/tools/agnes-ai","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Agnes-AI\n\n[English](README.md) | [中文说明](README_zh.md)\n\n![Agnes-AI](https://github.com/user-attachments/assets/4cbcaa09-e704-4c9b-90ba-b89b1b7fbc90)\nA unified Python CLI for Agnes AI models — text generation, image\nunderstanding, image generation, and video generation, all with zero external\ndependencies.\n\nBuilt by [AI Lab](https://github.com/1038lab). This repo wraps every Agnes API\nendpoint into a single `agnes.py` with sensible defaults, auto-translation,\nand dry-run validation — no pip install required.\n\n**What's inside:**\n\n```\nscripts/agnes.py   →  CLI (text, image understanding, image, video)\nSKILL.md           →  Agent skill for AI coding assistants\nexamples/server.py →  Web playground at http://localhost:8888\n```\n\n**Why use this?**\n\n- **Zero dependencies** — Python stdlib only, works out of the box\n- **Agent-ready** — ships with SKILL.md and playground for testing\n- **Auto-translate** — write prompts in any language\n- **Dry-run mode** — validate before spending credits\n- **Smart defaults** — sizes, frame counts, polling — all pre-configured\n- **Free to use** — no GPU needed, just an API key\n\n## Overview\n\n- **Text generation** — chat, tool calling, streaming with `agnes-3.0-flash`\n- **Image understanding** — describe images with `agnes-3.0-flash` multimodal\n- **Image generation** — text2img, img2img, multi-image compose with `agnes-image-2.5-flash`\n- **Video generation** — text2video, img2video, keyframe animation with `agnes-video-2.5-flash`\n- **Auto-translate** — non-English prompts translated to English automatically\n- **Zero dependencies** — Python stdlib only, no pip install required\n\n## Installation\n\nRequires Python 3.8+ and an Agnes AI API key.\n\n```bash\n# Clone the repository\ngit clone https://github.com/1038lab/Agnes-AI.git\ncd Agnes-AI\n\n# Optionally add scripts to your PATH\nexport PATH=\"$PWD/scripts:$PATH\"\n```\n\n## Getting an API Key\n\n1. Sign up at [https://apihub.agnes-ai.com](https://apihub.agnes-ai.com)\n2. Go to **API Keys** in your dashboard\n3. Click **Create API Key** and copy the `sk-...` key\n\n## Quick Start\n\n```bash\n# Set your API key\nexport AGNES_API_KEY=\"your-key-here\"\n\n# Or use the interactive setup\npython scripts/agnes.py setup\n\n# Generate text\npython scripts/agnes.py text --prompt \"Hello, introduce yourself\"\n\n# Describe an image\npython scripts/agnes.py text --prompt \"Describe this image in detail\" --image-url photo.jpg\n\n# Generate an image\npython scripts/agnes.py image text2img --prompt \"A cat wearing a spacesuit, digital art\"\n\n# Generate a video\npython scripts/agnes.py video text2video --prompt \"Ocean waves at sunset, cinematic quality\" --seconds 5\n```\n\n## CLI Reference\n\n### Global Options\n\n| Option | Description |\n|--------|-------------|\n| `--dry-run` | Print request body without calling the API |\n| `--no-translate` | Disable automatic prompt translation |\n| `--verbose` | Print debug info to stderr |\n\n### `agnes setup`\n\nSave your API key to your shell profile (`~/.zshrc` / `~/.bashrc` / `~/.profile`).\n\n```bash\nagnes setup\n```\n\n### `agnes text`\n\nText generation, chat completions, and image understanding (multimodal).\n\n```bash\nagnes text --prompt \"Write a poem about artificial intelligence\"\nagnes text --prompt \"Describe this image in detail\" --image-url photo.jpg\nagnes text --system \"Analyze the art style\" --image-url painting.png\nagnes text --prompt \"Write a sorting algorithm in Python\" --system \"You are a senior engineer\"\nagnes text --prompt \"Tell me a joke\" --stream\nagnes text --prompt \"History of computing\" --temperature 0.9 --max-tokens 2048\nagnes text --prompt \"What is 1+1?\" --message \"user: What is 2+2?\" --message \"assistant: 4\"\n```\n\n| Argument | Description |\n|----------|-------------|\n| `--prompt` | Prompt text (optional with `--image-url`) |\n| `--image-url` | Image file path or URL for multimodal understanding |\n| `--system` | System prompt |\n| `--message` | Multi-turn messages (repeatable, format `role: content`) |\n| `--stream` | Enable streaming output |\n| `--temperature` | Sampling temperature (default 0.7) |\n| `--top-p` | Top-p sampling (default 0.9) |\n| `--max-tokens` | Max output tokens (default 4096) |\n| `--tools-json` | Tool definitions as JSON |\n| `--tool-choice` | Tool selection strategy |\n| `--json-output` | Output as JSON |\n| `--model` | Model name (default `agnes-3.0-flash`) |\n\n### `agnes image`\n\nImage generation.\n\n![Agnes-AI Image](https://github.com/user-attachments/assets/dd371b71-e93a-4fb4-b98a-ad6ef4ffc78c)\n\n```bash\n# Text-to-image\nagnes image text2img --prompt \"Cyberpunk city at night\"\n\n# Image-to-image\nagnes image img2img --prompt \"Make it look like a watercolor\" --image-url https://example.com/photo.jpg\n\n# Compose multiple images\nagnes image compose --prompt \"Blend these images\"   --image-url https://example.com/img1.jpg   --image-url https://example.com/img2.jpg\n\n# Custom size and download directory\nagnes image text2img --prompt \"An oil painting\" --size \"1816x1024\" --output-dir ./output\n```\n\n| Argument | Description |\n|----------|-------------|\n| `mode` | Mode: `text2img` / `img2img` / `compose` (required) |\n| `--prompt` | Prompt text (required) |\n| `--image-url` | Reference image URL(s), repeatable |\n| `--size` | Image dimensions (default `1024x768`) |\n| `--output-dir` | Download directory (omit to print URLs only) |\n| `--model` | Model name (default `agnes-image-2.5-flash`) |\n\n### `agnes video`\n\nVideo generation with automatic polling and optional download.\n\n![Agnes-AI Video](https://github.com/user-attachments/assets/6ea1e190-412a-4950-913b-9f30d8aa7d1e)\n\n```bash\n# Text-to-video (modern 2.5-flash with seconds duration, auto-poll)\nagnes video text2video --prompt \"A butterfly flying through a flower field\" --seconds 5\n\n# Image-to-video\nagnes video img2video --prompt \"Animate this image\" --image-url https://example.com/photo.jpg --seconds 5\n\n# Keyframe video (start and end frames)\nagnes video keyframes --prompt \"Animation sequence\"   --image-url https://example.com/frame1.jpg   --image-url https://example.com/frame2.jpg --seconds 6\n\n# Modern aspect ratio and resolution (Flash 720P)\nagnes video text2video --prompt \"Waterfall\"   --seconds 6 --aspect-ratio 16:9 --size 720P   --download --output-dir ./videos\n\n# Legacy frame-count mode (agnes-video-v2.0)\nagnes video text2video --prompt \"Ocean waves\" --model agnes-video-v2.0   --width 1920 --height 1080 --num-frames 241 --frame-rate 30\n\n# Disable polling, just get the task_id\nagnes video text2video --prompt \"Sunset\" --no-poll\n```\nhttps://github.com/user-attachments/assets/25af3d70-c242-4c10-9320-6107f23b9320\n\n| Argument | Description |\n|----------|-------------|\n| `mode` | Mode: `text2video` / `img2video` / `keyframes` / `reference` (required) |\n| `--prompt` | Prompt text (required) |\n| `--image-url` | Reference image URL(s), repeatable |\n| `--audio-url` | Reference audio URL(s), repeatable |\n| `--ref-video-url` | Reference video URL(s), repeatable |\n| `--model` | Video model (default `agnes-video-2.5-flash`, or `agnes-video-2.5`, `agnes-video-v2.0`) |\n| `--seconds` | Duration in seconds (default `5`, range 4–12) |\n| `--aspect-ratio` | Aspect ratio (default `16:9`, choices: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`) |\n| `--size` | Resolution (default `720P`, choices: `720P`, `1080P`, `1K`, `2K`) |\n| `--width` | Video width in pixels (legacy v2.0) |\n| `--height` | Video height in pixels (legacy v2.0) |\n| `--num-frames` | Number of frames (legacy v2.0, default 121, must satisfy 8n+1, max 441) |\n| `--frame-rate` | Frames per second (legacy v2.0, default 24, range 1–60) |\n| `--seed` | Random seed for reproducibility |\n| `--num-inference-steps` | Number of denoising steps (legacy v2.0) |\n| `--negative-prompt` | Things to avoid in the video (legacy v2.0) |\n| `--no-poll` | Disable automatic polling |\n| `--poll-interval` | Poll interval in seconds (default 5) |\n| `--timeout` | Timeout in seconds (default 900) |\n| `--download` | Download video after completion |\n| `--output-dir` | Output directory |\n\n### `agnes poll`\n\nPoll for video generation status.\n\n```bash\nagnes poll VIDEO_ID\nagnes poll VIDEO_ID --poll-interval 5 --timeout 600\nagnes poll VIDEO_ID --download --output-dir ./videos\n```\n\n### `agnes smoke-test`\n\nRun end-to-end smoke tests in dry-run mode (no API calls).\n\n```bash\nagnes smoke-test\nagnes smoke-test --video-case text2video\n```\n\n## Features\n\n### Auto-Translation\n\nWhen 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.\n\n```bash\n# Auto-translate (default)\nagnes image text2img --prompt \"一只橘猫在窗台上晒太阳\"\n\n# Equivalent to manually translating then:\nagnes image text2img --prompt \"An orange cat basking in the sun on a windowsill\" --no-translate\n```\n\n### Automatic Media Upload\n\nFor `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.\n\n```bash\nagnes image img2img --prompt \"Make it cartoon style\" --image-url ./my-photo.jpg\nagnes video keyframes --prompt \"Scene transition\" --image-url ./start.png --image-url ./end.png\n```\n\n### Video Auto-Polling\n\nVideo generation polls for completion by default with real-time rendering progress updates (`0%` to `100%`). Pass `--download` to save the result locally.\n\n### Dry-Run Mode\n\nUse `--dry-run` to inspect the request payload without calling the API:\n\n```bash\nagnes image text2img --prompt \"test\" --dry-run\nagnes video text2video --prompt \"test\" --dry-run\n```\n\n## Usage Limits\n\n| Plan | Price | Limits |\n|------|-------|--------|\n| Free Access | $0 | Fair-use quota (no hard cap), basic TPS limit |\n| Starter | $2/mo | 1500 requests per 5 hours, higher RPM |\n| Plus | $5/mo | 7500 requests per 5 hours, higher RPM |\n| Pro | $25/mo | 30000 requests per 5 hours, higher RPM |\n\nSee [Common Error Codes](references/errors.md) for API error descriptions.\n\n## Changelog\n\n| Date | Changes |\n|------|---------|\n| 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 |\n| 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 |\n| 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 |\n\n## Zero-Dependency Philosophy\n\nThe entire project uses only Python standard library modules — no pip install required:\n\n- `urllib.request` — HTTP requests\n- `argparse` — CLI argument parsing\n- `json` — serialization\n- `os`, `sys`, `time`, `mimetypes` — system utilities\n- `re` — string processing (setup command)\n\n## Interactive Playground\n\nA web UI for all features — no terminal needed:\n\n```bash\n# One-click launch\nopen examples/start.command\n\n# Or manually\npython3 examples/server.py\n```\n\nOpen http://localhost:8888 to use:\n- **Text** — chat / streaming / JSON output / image description\n- **Image** — text2img / img2img / compose, all sizes with ratio labels\n- **Video** — text2video / img2video / start & end frames, with FPS and duration preview\n\n## Project Structure\n\n```\nAgnes-AI/\n├── scripts/          # Core Python modules\n│   ├── agnes.py      # CLI entry point and dispatch\n│   ├── text.py       # Text generation\n│   ├── image.py      # Image generation\n│   ├── video.py      # Video generation + polling\n│   ├── translate.py  # Auto-translation\n│   └── media.py      # Media upload and download\n├── references/       # API reference + error codes\n├── examples/         # Playground web UI + server\n├── tests/            # Smoke tests (no framework needed)\n└── agents/           # Agent configuration files\n```\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `AGNES_API_KEY` | Primary API key |\n| `AGNES_API_TOKEN` | Fallback API key |\n| `APIHUB_AGNES_API_KEY` | Fallback API key |\n| `AGNES_API_BASE` | API base URL (default `https://apihub.agnes-ai.com`) |\n\n## License\n\nGNU General Public License v3.0. See [LICENSE](LICENSE).\n\n## Links\n\n- [API Reference](references/api.md)\n- [Error Codes](references/errors.md)\n- [Agnes AI](https://agnes-ai.com)\n- [API Hub](https://apihub.agnes-ai.com)\n- [ComfyUI-Agnes-AI](https://github.com/1038lab/ComfyUI-Agnes-AI) — ComfyUI custom nodes built on this toolkit\n"}