1# Sapiens AI Agnes Image
2 
3Read when the user picks `--provider agnes` or sets `default_model.agnes`. Default model is `agnes-image-2.1-flash`.
4 
5## Models
6 
7**`agnes-image-2.1-flash`** (only model)
8 
9- Text-to-image and image-to-image (with `--ref`) in a single `/images/generations` endpoint
10- Supports reference images as public URLs or Data URI (base64)
11- Optimized for high information density, complex layouts, and rich details
12- Size rules: both dimensions divisible by 32 (720px exception), long edge ≤ 2048, total pixels ≤ ~4M
13- Default size: `1024x1024`; custom `--size` supports arbitrary WxH within the above rules
14- `--ar` supported: computed as 2048-based size (long edge ≤ 2048, short edge proportional, both snapped to 32px); `1:1` special-cased to `1024x1024`
15 
16## Response Format
17 
18- The sync API always returns a URL
19- Default (`--response-format file`): downloads the image and saves as `.png`
20- Pass `--response-format url`: writes the URL string to `.txt` instead
21 
22## `--n` Behavior
23 
24The Agnes API returns a single image per request regardless of the `n` parameter. Passing `--n > 1` triggers a local error from `validateArgs` before any API call is made.
25 
26## Behavior Notes
27 
28- API key required: `AGNES_API_KEY`
29- Base URL: `https://apihub.agnes-ai.com/v1` (override with `AGNES_BASE_URL`)
30- Model override: `AGNES_IMAGE_MODEL` env
31- `response_format` is always embedded in `extra_body` (not at request top level)
32- Reference images: local files converted to Data URI base64 inline; remote URLs passed through
33- Rate limit defaults: concurrency=3, startIntervalMs=1100 (override via `BAOYU_IMAGE_GEN_AGNES_CONCURRENCY` / `BAOYU_IMAGE_GEN_AGNES_START_INTERVAL_MS`)
34- Timeout: 120s per request
35 
36## Size Resolution
37 
38- `--size <WxH>` wins over `--ar`
39- `--ar` maps to a concrete size using the algorithm: long edge ≤ 2048, short edge proportional, both dimensions snapped to 32px
40- `--ar 1:1` is special-cased to `1024x1024`
41 
42### Common `--ar` Results
43 
44| Aspect Ratio | Result |
45|--------------|--------|
46| `1:1` | `1024x1024` |
47| `16:9` | `2048x1152` |
48| `4:3` | `2048x1536` |
49| `3:2` | `2048x1376` |
50| `21:9` | `2048x896` |
51| Unlisted ratio | Computed on the fly (portrait mirror swaps width/height) |
52 
53## Official References
54 
55- [Agnes AIGC API Hub](https://apihub.agnes-ai.com)
56