Resolve a batch

This is what pixloom-client.js calls. You rarely need it directly, but it is the right endpoint any time one screen needs many images at once: a grid, a feed, a server-rendered page, a static build step.

It takes either kind of key, which is the whole point. A publishable key can call it from the browser, so the script tag ships in page source without exposing anything.

curl -X POST https://pixloom.dev/api/v1/embed/resolve \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "elements": [
      { "id": "hero", "prompt": "cozy bookstore at sunset", "style": "watercolor" },
      { "id": "sidebar", "shortcut": "weekly-banner" },
      { "id": "footer", "prompt": "stack of books", "mode": "instant" }
    ]
  }'

{
  "results": [
    { "id": "hero", "status": "ready", "imageUrl": "https://...", "imageId": "b71e..." },
    { "id": "sidebar", "status": "generating", "jobId": "3f6c..." },
    { "id": "footer", "status": "ready", "imageUrl": "https://...", "match": "nearest", "matchScore": 0.86, "poolImageId": "9c41..." }
  ]
}

Results come back in the order you sent them, one per element, each carrying the id you chose. Anything generating has a jobId to poll.

Elements

One to fifty per request. Each element needs either a prompt or a shortcut.

The three kinds of element

A shortcut resolves to the best image for that permalink. It never starts a generation and never touches your quota.

A prompt in generate mode returns ready with an image if we already have one for that exact prompt and style, and otherwise starts a job and returns generating. This is what makes the second visitor to a page see images immediately.

A prompt in instant mode always returns the closest image from our shared library, in one round trip. Never a job, never a generation, free on every plan. match is exact or nearest, and matchScore is how close, from 0 to 1.

Results

One element failing never fails the batch. An element that would push you past your quota comes back failed while everything else in the request still resolves, so a single bad slot cannot blank out a page.

Responses