Generate an image
POST /api/v1/generate starts a generation and hands you back a job to poll.
curl -X POST https://pixloom.dev/api/v1/generate \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "prompt": "cozy bookstore at sunset", "style": "watercolor" }'
# 202 { "jobId": "3f6c2a10-...", "status": "queued" }The response comes back in milliseconds and the image does not exist yet. Poll the job every second or two until it says completed. A generation usually takes ten to fifteen seconds.
Needs a secret key. Publishable keys cannot generate.
Parameters
| Field | Type | Default | Notes |
|---|---|---|---|
prompt | string | required | 1 to 2000 characters. |
style | string | none | A preset id or one of your own styles. See styles. |
strength | number | 1 | 0 to 1. How hard the style is applied. |
character | uuid | none | A character to put in the image. See characters. |
width | integer | 1024 | 256 to 2048, in multiples of 64. |
height | integer | 1024 | 256 to 2048, in multiples of 64. |
format | png, jpeg or webp | webp | |
ageBuckets | array | none | One of kids, bigkids, adults. At most one. Leave it out for all ages. |
mode | generate or instant | generate | Instant mode is below. |
Anything outside those ranges comes back as a 400 with a details object naming the field, rather than being quietly clamped.
Character appearance
Generations respect the character's saved behavior, set in the dashboard under Across styles. Match ("Adapt to the style") adapts its appearance to the scene style. Lock ("Keep one look") keeps its chosen appearance while the surroundings use the scene style. An exact locked style takes precedence over a locked family; with neither configured, lock preserves the original appearance.
The first use of a supported visual family takes longer while Pixloom prepares a reusable character reference. The job waits for that reference before creating the scene. If preparation fails, the job reports failure and you can retry. Later scenes in the same family reuse the reference until the character or its source images change. Custom and unmapped styles use the original references.
Mixed styles are best-effort. Cartoon characters work well in photographic scenes, but photographic characters can still acquire illustrated outlines or shading in cartoon scenes.
Instant mode
Set mode to instant and you get an image in the same response. There is no job to poll.
curl -X POST https://pixloom.dev/api/v1/generate \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "prompt": "cozy bookstore at sunset", "style": "watercolor", "mode": "instant" }'{
"status": "completed",
"imageUrl": "https://...",
"imageId": "b71e...",
"match": "nearest",
"matchScore": 0.88,
"poolImageId": "9c41..."
}This is the closest image from our shared library, not a fresh generation. That means it is free: instant calls do not count against your monthly generations and work on every plan, including free.
match tells you what you got. exact means someone asked for this exact prompt and style before. nearest means we found something close, and matchScore is how close, from 0 to 1. poolImageId is the library image itself, which you can save as a permalink from your dashboard.
If nothing in the library is close enough, you get a 404. Fall back to a normal generate call when that matters.
Responses
| Status | Body |
|---|---|
202 | { "jobId": "...", "status": "queued" } |
200 | The instant result above. Only for mode: "instant". |
400 | { "error": "Invalid request", "details": { ... } }, or { "error": "Invalid JSON" } |
401 | Missing or invalid key. |
402 | Out of generations. Carries used, limit and resetAt. |
403 | Account not approved, or you used a publishable key. |
404 | Instant mode found nothing close enough. |
429 | Over your per-minute rate limit. |
Every 202 and 402 also carries X-Quota-Used, X-Quota-Limit and X-Quota-Reset, so you always know where you stand without a second call. See errors and limits.