Algovate/agnes-image

Agnes Image Generation

agnes-img is a wrapper around agnes image generate: it supports the same parameters, with additional support for the 2.5 model and automatic fallback. Currently, 2.5 (agnes-image-2.5-flash) is the default, and 2.1 (agnes-image-2.1-flash) serves as the fallback and compatibility tier.

Pre-check

agnes key status

• If "status": "missing", the API key is not configured. Ask the user to generate an API Key at https://platform.agnes-ai.com, then run agnes key set <KEY> (writes to local config) or set the environment variable AGNES_API_KEY.
• Do not fabricate a key, and do not write the key into project files or reply body.

Model Selection

Requirement	Usage
Default (production)	Pass nothing → agnes-image-2.5-flash
Specify 2.1	--model 2.1
Change default tier	Environment variable AGNES_IMAGE_MODEL=2.1
Disable auto-fallback	--no-fallback (or AGNES_IMAGE_FALLBACK=0)

• Priority: --model > AGNES_IMAGE_MODEL > default (2.5).
• When 2.5 returns a 5xx, it will automatically retry once with 2.1; stderr will print role=fallback; the reply should indicate the actual model used.
• stderr always prints generated with <model>; use this to annotate the model in the reply.

Text-to-Image

agnes-img --prompt "description" --size 2K

• On success, stdout contains only the image URL; model name, task ID, fallback info, and errors go to stderr.
• --size supports tiers 1K / 2K / 3K / 4K, and also accepts exact values like 1024x768 (default is 1024x768).
• The tier default is 1:1; for 16:9, 9:16, or other aspect ratios, pass the corresponding native dimensions, e.g., for 16:9 use 1312x736 (1K) or 2624x1472 (2K), for 9:16 use 736x1312.

Image-to-Image and Multi-Image Composition

agnes-img --prompt "convert to cyberpunk night scene" --image ./ref.png
agnes-img --prompt "merge these two reference images into a poster" --image ./a.png --image ./b.png

• --image can be repeated, and supports local paths, public URLs, or Data URIs; local files are automatically converted to Data URIs.
• For image editing, a prompt describing "what to keep, what to change" yields more stable results.

Saving and Displaying (Mandatory)

The URL is temporary; it must be downloaded to the workspace:

mkdir -p output output/drafts
curl -sSL "<URL>" -o "output/agnes-$(date +%Y%m%d-%H%M%S).png"
ls -l output/*.png

• Confirm the file is not empty (using file / size > 0) before delivering.
• Use read_image to preview the result; display it in the reply using ![description](output/xxx.png), or with present as needed.

Output Directory Convention (Must Follow)

output/                       Deliverables, permanent retention
  <subject>.png               Main image for a subject, e.g., eagle-hare.png
  <subject>-<variant>.png     Another variant of the same subject, e.g., eagle-hare-ink.png
output/drafts/                Drafts / superseded versions, can be cleaned after 7 days
  <subject>-<variant>-<YYYYMMDD-HHMM>.png

Rules:

1. Deliverables go directly to output/<subject>.png; use lowercase hyphens, English semantic names; avoid ephemeral suffixes like -v2, -final, -copy.
2. Old images that are superseded by a new version should be mv'd to output/drafts/<subject>-<timestamp>.png once the new image is confirmed, to avoid cluttering output/.
3. Experimental drafts not intended for delivery (trial compositions, parameter tests) should be written directly to output/drafts/.
4. For cleanup, always use agnes-gc, never manually rm the entire output:

agnes-gc              # Preview: drafts older than 7 days
agnes-gc --apply      # Execute
agnes-gc --all        # Preview: clear all drafts

agnes-gc only operates on directories named drafts; deliverable images in output/ are never deleted by it.

Troubleshooting

• {"ok":false,"error":{"type":"auth",...}}: Key not configured or invalid; first run agnes key status.
• type: "validation": Invalid parameters (e.g., unsupported model, missing --prompt); fix per hint, do not blindly retry.
• 2.5 returns 5xx: automatically falls back to 2.1; if stderr contains role=fallback, the result is from the fallback, and this should be noted in delivery.
• Generation typically takes 10–60 seconds; set Bash timeout to at least 180000 ms.
• Run only one generation task at a time to avoid concurrent quota usage.

Compatibility Notes

The legacy agnes image generate command is still available, but its --model only accepts agnes-image-2.1-flash / agnes-image-2.0-flash; it does not support 2.5. When 2.5 or automatic fallback is needed, always use agnes-img.