Render a URL
GET /api/v1/render is a URL that returns an image. Paste it anywhere a URL is loaded.
https://pixloom.dev/api/v1/render?prompt=cozy+bookstore+at+sunset&style=watercolor&key=sk_live_...The first request generates the image and takes a few seconds. Every request after redirects straight to the finished file. No polling, no job, no JSON.
This is the endpoint for places that only understand URLs: an email, a Slack message, a Notion page, a Figma fill, an iOS shortcut, a CMS field that wants an image address.
This endpoint needs a secret key, and the key usually has to sit in the URL. Only use it where the URL stays private. For a public page, use the image proxy, which takes no key at all.
Parameters
| Param | Type | Default | Notes |
|---|---|---|---|
prompt | string | required | Missing gives a 400. |
style | string | none | A preset id or one of your own. |
strength | number | 1 | 0 to 1. |
character | uuid | none | |
width | integer | 1024 | Clamped to 256 to 2048, rounded to a multiple of 64. |
height | integer | 1024 | Same. |
format | png, jpeg or webp | webp | Anything else becomes webp. |
age | string | none | Comma-separated kids, bigkids, adults. Unknown values are dropped. |
key | string | Your key, when you cannot set a header. |
Unlike generate, out-of-range numbers are clamped rather than rejected. A URL in an email cannot handle a validation error, so it gets the nearest sensible image instead.
Character requests follow the character's saved match or lock behavior. The first request may take longer to prepare its appearance. Subsequent scenes reuse that preparation. Changing source images invalidates the character's cached appearance. Character requests skip the permalink's active-image shortcut and use the character revision when checking cached images.
What you get back
Always a 302 to the image, cached for ten minutes. What sits behind the redirect depends on what already exists, in this order:
- An image you pinned for this permalink, while its refresh window holds.
- The cached image for this exact prompt and style.
- The best performing image for this prompt, by clicks and impressions.
- A brand new generation.
Only the last one costs a generation. A popular URL is almost always a redirect to a file we already have.
Running out of generations
If you are out of quota, the endpoint first looks for any image you already made from this exact prompt and serves that. Only when there is nothing at all do you get a 402. A page that has been running for a while keeps showing images after you hit your limit.
Responses
| Status | Body |
|---|---|
302 | Redirect to the image. |
400 | Missing prompt or invalid character UUID. |
401 | Missing or invalid key. |
402 | Out of generations and no earlier image to fall back on. |
403 | Account not approved, publishable key, or a domain that is not on the key. |
404 | Character not found or belongs to another account. |
429 | Over your per-minute rate limit. |
502 | Character references could not be read, or image generation failed. Try again. |