Emperor API

Generate images from your own code.

A real REST API for Emperor's image models. The same pipeline, billing, and moderation as the web app, callable from a server you control.

Prefer MCP? →

01. Authentication

One Bearer token per key.

Create a key from /developers. The raw secret is shown once at creation. Emperor only ever stores its hash, so if you lose it, revoke it and create a new one. Send it as a standard Bearer token on every request:

Authorization: Bearer emp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

02. Generate an image

POST /api/v1/images

Generation is synchronous. The request doesn't return until the image is ready (or held for moderation). image_url is a temporary link, valid for 15 minutes; download it promptly.

curl -X POST https://emperor.tools/api/v1/images \
  -H "Authorization: Bearer $EMPEROR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a golden retriever wearing sunglasses, studio lighting",
    "model": "grok-imagine-image-quality",
    "resolution": "1K"
  }'

Response

{
  "id": "5be4d2f8-f505-48e4-ba81-c630578633e6",
  "status": "succeeded",
  "image_url": "https://...r2.cloudflarestorage.com/...",
  "model": "grok-imagine-image-quality",
  "resolution": "1K",
  "credits_charged": 100
}

03. Moderation holds

GET /api/v1/images/{id}

Most generations come back as succeeded immediately. A small fraction are held for human moderation review and come back as needs_review with a null image_url: poll this endpoint until the status changes to succeeded or rejected. Credits are only charged once, at generation time, regardless of the review outcome.

curl https://emperor.tools/api/v1/images/5be4d2f8-f505-48e4-ba81-c630578633e6 \
  -H "Authorization: Bearer $EMPEROR_API_KEY"

04. Models & pricing

Same models, same prices as the app.

Fetched live from GET /api/v1/models: no separate API price list to drift out of sync.

Model	Description	1K	2K
grok-imagine-image	Fastest, cheapest. Good for drafts and iteration.	50 credits	50 credits
grok-imagine-image-2.0	Higher fidelity, supports multi-image reference input.	120 credits	150 credits
grok-imagine-image-quality	Recommended default. Best single-reference realism.	100 credits	150 credits
gpt-image-2	OpenAI's image model, strong at text-in-image and illustration.	120 credits	350 credits
flux-dev	Open-weight FLUX.1 Dev. Strong general-purpose realism.	50 credits	50 credits
wan-2.5	Wan 2.5, an alternative general-purpose image model.	80 credits	80 credits

05. Rate limits

Scoped per key, sized by your plan.

Each key is rate-limited independently of your browser session. A script hammering the API won't throttle you in the app. The cap matches your account's plan tier:

Plan	Requests / min
Free / Trial	20
Starter	20
Creator	40
Studio	80

06. Current scope

What v1 does, and doesn't, do.

✓Image generation, on every model the app supports.
–Batch, video, and enhance generation aren't exposed via the API yet. Coming in a future version.
–No CORS. This is a server-to-server API. Never call it, or paste your key, from browser-side code.
–No per-key spend caps beyond your account balance. Revoke a key from /developers to cut it off immediately.