API REFERENCE

Prompt in, print file out.

Generate images, or transparent 300 DPI T-shirt artwork, with one request. Jobs are asynchronous: you queue a job, poll it, and download the PNG.

Connect an LLM or agent

Point your agent at one of these. Both stay current with the service:

https://img.richemoji.com/openapi.json: OpenAPI 3.1, for tool and function-calling frameworks, custom GPT actions and API clients.
https://img.richemoji.com/llms.txt: a plain-text guide to paste into a system prompt.

Give the agent the key through its secret or env configuration (for example IMAGEGEX_KEY), not inside the prompt text.

Authentication

Every /v1 request except /v1/plans needs your client key:

Authorization: Bearer igx_your_key

Quick start

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"}}'
# 202 {"job_id":"51759b3a…","status":"pending","status_url":"/v1/jobs/51759b3a…"}

curl -s https://img.richemoji.com/v1/jobs/51759b3a… -H "Authorization: Bearer $IMAGEGEX_KEY"
# {"status":"succeeded","image_url":"/v1/jobs/51759b3a…/image","print":{…}}

curl -s https://img.richemoji.com/v1/jobs/51759b3a…/image \
  -H "Authorization: Bearer $IMAGEGEX_KEY" -o tiger_print.png

Python

import os, time, requests

API = "https://img.richemoji.com"
H = {"Authorization": f"Bearer {os.environ['IMAGEGEX_KEY']}"}

job = requests.post(f"{API}/v1/images", headers=H, json={
    "prompt": "Retro skull wearing headphones, hot pink and cyan, halftone shading",
    "output": "print", "print": {"size": "12x16"},
}).json()
while (status := requests.get(f"{API}/v1/jobs/{job['job_id']}", headers=H).json())["status"] in ("pending", "running"):
    time.sleep(3)
if status["status"] == "failed":
    raise SystemExit(status["error"])
open("print.png", "wb").write(requests.get(API + status["image_url"], headers=H).content)
print(status["print"]["warnings"])

POST /v1/images

Queues a job and returns 202 with job_id and status_url.

Field	Type	Notes
`prompt`	string, required	1–2000 characters. Lettering is attempted but spelling is not guaranteed.
`output`	`"standard"` \| `"print"`	Default `standard`. `print` returns a transparent 300 DPI PNG.
`print.size`	`"12x16"` \| `"10x10"` \| `"4x4"`	Canvas in inches: 3600×4800, 3000×3000 or 1200×1200 px. Default `12x16`.
`print.align`	`"center"` \| `"top"`	Vertical placement on the canvas. Default `center`.
`print.prompt_assist`	boolean	Default `true`. Frames the prompt as standalone artwork and strips “T-shirt”/“mockup” wording.
`seed`	integer	0–4294967295. Fix it to reproduce a result; change it to get a different take.
`width`, `height`	integer	512–1024, multiples of 64. Print jobs pick a suitable default.
`reference_image_base64`	string	Optional PNG or JPEG, ≤10 MB and ≤4 MP, for a loose variation.
`denoise`	number	0.05–0.8, default 0.35. How far a variation moves from the reference.

Jobs and downloads

Endpoint	Returns
`GET /v1/jobs/{id}`	Status: `pending`, `running`, `succeeded` or `failed`, plus `error`, `seed`, `image_url`. Print jobs add `print` details and `raw_image_url`.
`GET /v1/jobs/{id}/image`	The PNG. For print jobs this is the print file; `?variant=raw` returns the original generation.
`GET /v1/jobs`	Your 100 most recent jobs.
`GET /v1/usage`	`monthly_quota`, `completed_images`, `reserved_images`, `remaining_images`.
`GET /v1/models`, `GET /v1/plans`, `GET /health`	Models, plans, and service status (`comfyui_connected`).

Poll every 2–3 seconds. A standard image takes under 10 s and a print file about 20 s once running.

Print files

A print job generates the design on a flat background, removes the background (BiRefNet), upscales the art (Real-ESRGAN) and places it on the canvas. The PNG is RGBA with a transparent background, an sRGB ICC profile and 300 DPI metadata, ready for print-on-demand upload.

The print object reports canvas_px, art_px, art_inches, generated_px, upscale_factor and warnings. Show warnings to whoever approves the print. If no clean design can be cut out, the job fails with a reason and does not use your allowance; retry with another seed.

Prompting: describe the design itself, not a shirt. Bold outlines and flat colors cut out best.

Errors and limits

Status	Meaning
`400`	Invalid body. `error` says which field.
`401`	Missing or invalid key.
`403`	Subscription inactive, or key revoked.
`429`	Five jobs already queued for you (wait and retry), or the monthly allowance is used up.

Each succeeded job uses one image. Allowances reset at 00:00 UTC on the 1st of each month.