API reference
A handful of endpoints cover most of what you will ever need.
Every call carries a key. Put it in the Authorization header as Bearer sk_live_..., or as ?key= on endpoints you open in a browser or an email.
- Secret keys (
sk_live_) can do everything. Keep them on a server. - Publishable keys (
pk_live_) can only fetch images for the script tag. Safe to ship in page source.
The base URL is https://pixloom.dev.
The endpoints
| Endpoint | What it does |
|---|---|
POST /api/v1/generate | Start making an image. Returns a job, not an image. |
GET /api/v1/job/:jobId | Check on a job. Returns the image URL when it is done. |
GET /api/v1/render | A URL that returns an image. Generates once, then redirects to the file. |
GET /api/v1/image/:id | Redirect to an image you already made, and pin or reject it. |
GET /api/v1/styles | List the styles your plan can use. |
GET /api/v1/characters | List the characters you can put in an image. |
POST /api/v1/embed/resolve | Resolve a batch of images at once. What the script tag calls. |
POST /api/v1/analytics/events | Tell us an image was seen or clicked. |
GET /api/img/{handle}/{name} | A permanent URL for a named image. No key in the URL. |
GET /api/health | Is Pixloom up? No key needed. |
Health is the one endpoint without a page, because there is nothing to say:
curl https://pixloom.dev/api/health
# 200 { "status": "ok", "service": "pixloom", "timestamp": "2026-09-15T12:00:00.000Z" }How a generation works
- You
POSTa prompt and, optionally, a style. You get back ajobIdand a202. - You poll the job every second or two. It goes
queued,processing,completed. - When it completes, the response carries
imageUrl. That URL is yours to use.
Jobs are kept for an hour. After that, poll and you get a 404, but the image itself is safe in your dashboard.
Instant mode
Add "mode": "instant" to a generate call and you get an image back in the same response, no job, no waiting. It is the closest match from our library rather than a fresh generation, so it costs nothing against your quota and works on every plan.
When something goes wrong
Errors and limits covers every status code, the rate limits per plan, and the quota headers that ride along on every generation. The short version:
| Status | Meaning | What to do |
|---|---|---|
402 | Out of generations this month. | Wait for the reset, or upgrade. The response says when. |
403 with pending_approval | Your account is not approved yet. | Wait for the email. Retrying will not help. |
429 | Too many requests this minute. | Back off for retryAfterMs, then try again. |