# Imagegex API

> Generate images and transparent, print-ready T-shirt artwork (300 DPI PNG) from a text prompt. Base URL: https://img.richemoji.com. Machine-readable spec: https://img.richemoji.com/openapi.json

## Authentication

Send `Authorization: Bearer igx_...` on every /v1 request except /v1/plans. Keys are issued per client; never put a key in a URL, a log, or a reply to the user.

## Workflow (asynchronous)

1. `POST /v1/images` with a JSON body. You get HTTP 202 and `{"job_id", "status": "pending", "status_url"}`.
2. Poll `GET /v1/jobs/{job_id}` every 2-3 seconds until `status` is `succeeded` or `failed`. Standard images take under 10 s once running and print files take about 20 s. Jobs queue behind others, so allow up to a few minutes.
3. On `succeeded`, download `GET /v1/jobs/{job_id}/image` (PNG bytes, same Authorization header).
4. On `failed`, read `error`. Print jobs fail with a readable reason when no clean design could be cut out; retry with a different `seed` or a simpler prompt. Failed jobs do not count against the allowance.

## Request body for POST /v1/images

- `prompt` (required, 1-2000 chars): subject, style, colors. Lettering is attempted but spelling is not guaranteed, so check the result before using it.
- `output`: `"standard"` (default) for a normal image, or `"print"` for a transparent print file.
- `print` (only with output "print"):
  - `size`: `"12x16"` (default, 3600x4800 px full front), `"10x10"` (3000x3000), `"4x4"` (1200x1200 pocket).
  - `align`: `"center"` (default) or `"top"` (top margin; usual for full-front prints).
  - `prompt_assist`: true (default). Rewrites the prompt into standalone artwork on a flat background and strips words like "T-shirt" and "mockup". Leave it on.
- `seed`: integer 0-4294967295 for reproducible results. Omit it for a random seed.
- `width` and `height`: 512-1024 in steps of 64. Defaults are 1024x1024, 768x1024 for a 12x16 print, and 1024x1024 for square prints. Usually omit them for print jobs.
- `reference_image_base64` and `denoise` (0.05-0.8, default 0.35): make a loose variation of a PNG or JPEG. This is not a precise editor.

## Print output details

A succeeded print job includes `print`: canvas_px, dpi (300), art_px, art_inches, generated_px, upscale_factor, coverage and `warnings`. Show any warnings to the user. `raw_image_url` (`/v1/jobs/{id}/image?variant=raw`) is the original generation before background removal. The print PNG is RGBA with a transparent background, sRGB ICC profile and 300 DPI metadata, ready to upload to print-on-demand services.

Prompting tips for print: describe the design itself ("retro skull wearing headphones, hot pink and cyan, bold black outlines"), not a shirt. Bold outlines and flat colors cut out best. Avoid asking for photographic backgrounds or scenes that fill the frame; the design must be separable from its background.

## Limits

- Up to 5 queued or running jobs per client. More returns HTTP 429 "Generation queue is full", so wait and retry.
- Monthly allowance: each succeeded job uses 1 image. HTTP 429 "Monthly image quota reached" means the allowance is used up; it resets at 00:00 UTC on the 1st. Check `GET /v1/usage` (`remaining_images`).
- HTTP 403 means the subscription is inactive or the key was revoked.
- `GET /health` reports `generation_available`. While it is false, jobs wait in the queue and complete once a generator is back.
- Jobs may run on a cloud fallback model when the primary GPU is offline. Then `seed` has no effect, and print jobs can take a minute or two longer.

## Example

```
curl -s https://img.richemoji.com/v1/images \
  -H "Authorization: Bearer $IMAGEGEX_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Roaring tiger head, orange and teal, bold black outlines, the word WILD below","output":"print","print":{"size":"12x16","align":"top"}}'
# -> {"job_id":"51759b3a...","status":"pending","status_url":"/v1/jobs/51759b3a..."}
curl -s https://img.richemoji.com/v1/jobs/51759b3a... -H "Authorization: Bearer $IMAGEGEX_KEY"
curl -s https://img.richemoji.com/v1/jobs/51759b3a.../image -H "Authorization: Bearer $IMAGEGEX_KEY" -o tiger_print.png
```

## Other endpoints

- `GET /v1/jobs`: your 100 most recent jobs.
- `GET /v1/usage`: allowance and usage for the current UTC month.
- `GET /v1/models`: available models (only z-image-turbo).
- `GET /v1/plans`: subscription plans (no key needed).