Getting started

Pixora renders images with its own model on dedicated GPUs. A 1024×1280 image takes about 10 seconds once a machine is running, and up to 2 minutes when one has to start. The next section explains why that shapes how you write your integration.

npm install @vovix/pixora

import { Pixora } from '@vovix/pixora'

const px = new Pixora({
  // baseUrl defaults to https://api.pixora.vovix.io/v1
  apiKey: process.env.PIXORA_KEY,
})

const { styles } = await px.listStyles()

You do not need the SDK. The API is plain HTTP and JSON — see Reference.

Authentication

Two paths. Use exactly one.

Generating images

Every image belongs to a style. A style carries the shared art direction, which is what makes ten images look like one photographer took them.

Send prompt as one string, or fill the nine recipe slots and pass them asrecipe alongside the composed prompt. Slots are stored with the image so the Studio can show and edit them one by one. Keys: shot, subject, wear, scene, light, palette, story, medium, lens.

const { images } = await px.createImages({
  styleId: 'sty_...',
  prompt: 'Medium shot of a woman in her late twenties, ivory silk slip dress, rooftop at golden hour…',
  width: 1024,
  height: 1280,
  steps: 8,
  count: 4,
})
// images[i].status === 'generating' — the picture does NOT exist yet

This call returns immediately. Each image gets its database row before the job reaches the queue, so a dropped connection or a closed tab never loses track of an image — ask again by id and it is there.

Five engines

Pick the model with engine. The free one is open to every account the moment it signs up;anima exists in the API but is not open to any account yet — see the note below the table.

await px.createImages({ styleId, prompt, engine: 'sdxl-turbo', steps: 2 })
await px.gpu('sdxl-turbo')   // same shape as px.gpu()

With sdxl-turbo, realvis-xl, animagine-xl and anima, width/height only choose the aspect; the image is rendered in that model's own class and the real size comes back on the image (1024×1280 becomes 448×576 on sdxl-turbo, 896×1152 on the three 1024 px engines). Images made before 2026-09-06 carry engine: "pixora-1", the old name of z-image-turbo.

Why you wait, and how to wait correctly

GPUs shut down when idle so they do not burn money. That means the first call after a quiet period has to boot a machine and load the model. Measured:

const done = await px.waitFor(images.map((i) => i.assetId), {
  onProgress: (n, total) => console.log(`${n}/${total}`),
})

To tell your users which row of that table they are in before they click, ask the worker. The same state drives the coloured dot in Studio.

const gpu = await px.gpu()
// gpu.state: 'ready' | 'starting' | 'off' | 'error'
// gpu.reason: a sentence you can show as-is
// gpu.queue.waiting: images ahead of yours

There are no webhooks and no server-sent events. The reason is cost: holding a connection open for the whole wait runs about twenty times more expensive than polling every three seconds, and it still dies when someone reloads the page.

Styles

A style's promptPreset is appended to the end of every prompt. The end, not the beginning: Pixora reads the opening as the subject and the rest as technical direction, so leading with art direction drowns out what you actually asked for.

await px.createStyle({
  title: 'Harbour town, 2D',
  promptPreset: '2D animated series background art, flat cel shading, clean bold line art',
  defaultWidth: 1472,
  defaultHeight: 832,
})

A style can only be deleted once it is empty. Cascading the delete would drop the rows easily and leave the image files behind — garbage nobody knows to collect.

Free images without the GPU

Not every image needs to be generated. Search Wikimedia Commons for licensed photos and illustrations and import the picks straight into a style. This runs on the API side and finishes in one call, so it does not depend on GPU hours. Imports count toward the account's daily image limit like generated images do.

Two sources, chosen with provider:

const { providers } = await px.sources()                     // ['licensed', 'web']

const licensed = await px.search('old town street at dusk', { limit: 12 })                   // provider defaults to 'licensed'
const web      = await px.search('old town street at dusk', { provider: 'web', limit: 12 })

const { images, failed } = await px.importImages({
  styleId,
  kind: 'background',
  items: licensed.results.slice(0, 3),   // a search result is already a valid import item
})

curl "https://api.pixora.vovix.io/v1/search?q=mountain+lake&provider=web&limit=12" \
  -H "x-api-key: $PIXORA_API_KEY"

Imported images carry engine: "import" and a source block (provider, page URL, author, license). Show the credit where the license asks for it — the Studio does. Up to 8 images per call, 15 MB each, JPEG/PNG/WebP. The first web search after a quiet period can take ~10 s while the search backend warms up; the API answers504 SOURCE_WARMING with Retry-After if it cannot make it in time.

Limits and quotas

Three gates protect the GPUs, and every rejection carries a machine-readable code. They apply to z-image-turbo; the open engines (sdxl-turbo, realvis-xl, animagine-xl) skip approval and the schedule and only has its own daily limit (and a 503 CLOSED while an admin pauses it).anima also skips approval and the schedule, but returns 503 CLOSED for everyone right now regardless of quota — see the licensing note above.

GET /v1/gpu returns schedule and account so you can show the state before your user clicks; add ?engine=sdxl-turbo for the free tier's own limit and counter.

Over quota returns 429 with a Retry-After header. The SDK surfaces that as err.retryAfter in seconds so you are not retrying blind.

Errors

Reference

Key management (/v1/keys) is deliberately not available to API keys — only to a signed-in session. Otherwise a leaked key could mint new keys and revoking the original would mean nothing.