Skip to content

Image

Images from a prompt or from a starting image, as media jobs with POST /v1/media/jobs.

Access: Keys with the media:read or media:generate scope, on an account with media access granted by Albastar Corp.

Image jobs make images from a prompt, or from a starting image and a prompt, with POST /v1/media/jobs and kind image; GET /v1/media/jobs/{id} returns the job with its image files once state is done.

Quick example

The example queues one zimage-turbo image at 16:9, then reads the job with ?wait=60 until the job settles.

curl

JOB=$(curl -s https://api.albastov.com/v1/media/jobs \
  -H "Authorization: Bearer $ALBASTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "image", "model": "zimage-turbo",
       "params": {"prompt": "A lighthouse on a basalt cliff at dusk",
                  "aspect": "16:9", "seed": 42}}' \
  | python3 -c 'import json, sys; print(json.load(sys.stdin)["id"])')

until curl -s "https://api.albastov.com/v1/media/jobs/$JOB?wait=60" \
  -H "Authorization: Bearer $ALBASTAR_API_KEY" -o job.json \
  -w '%{http_code}' | grep -q 200; do :; done
cat job.json

Python

import json
import os
import urllib.request

BASE = "https://api.albastov.com/v1"
HEADERS = {
    "User-Agent": "my-app/1.0",
    "Authorization": f"Bearer {os.environ['ALBASTAR_API_KEY']}",
    "Content-Type": "application/json",
}


def call(path, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(BASE + path, data=data, headers=HEADERS)
    with urllib.request.urlopen(req, timeout=120) as res:
        return json.load(res)


job = call("/media/jobs", {
    "kind": "image",
    "model": "zimage-turbo",
    "params": {
        "prompt": "A lighthouse on a basalt cliff at dusk",
        "aspect": "16:9",
        "seed": 42,
    },
})
while job["state"] in ("queued", "waiting_device", "running"):
    job = call(f"/media/jobs/{job['id']}?wait=60")
print(job["state"], [r["url"] for r in job["results"]])

JavaScript

const base = "https://api.albastov.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.ALBASTAR_API_KEY}`,
  "Content-Type": "application/json",
};

async function call(path, body) {
  const res = await fetch(base + path, {
    method: body ? "POST" : "GET",
    headers,
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

let job = await call("/media/jobs", {
  kind: "image",
  model: "zimage-turbo",
  params: {
    prompt: "A lighthouse on a basalt cliff at dusk",
    aspect: "16:9",
    seed: 42,
  },
});
while (["queued", "waiting_device", "running"].includes(job.state)) {
  job = await call(`/media/jobs/${job.id}?wait=60`);
}
console.log(job.state, job.results.map((r) => r.url));

The response is the settled job, with one PNG result of 1344 by 756 pixels:

JSON
{
  "id": "mj_bKAiyenqLjMs9kwfcS4Z5k",
  "kind": "image",
  "model": "zimage-turbo",
  "label": "",
  "state": "done",
  "waiting": null,
  "position": null,
  "priority": "batch",
  "params": {
    "aspect": "16:9",
    "cfg": 1,
    "count": 1,
    "format": "png",
    "loras": [],
    "negative_prompt": "",
    "prompt": "A lighthouse on a basalt cliff at dusk",
    "sampler": "res_multistep",
    "scheduler": "simple",
    "seed": 42,
    "shift": 3,
    "steps": 8
  },
  "results": [
    {
      "index": 0,
      "url": "…/v1/media/files/mj_bKAiyenqLjMs9kwfcS4Z5k/0.png",
      "content_type": "image/png",
      "bytes": 1252884,
      "width": 1344,
      "height": 756,
      "seed": 42,
      "thumb_url": "…/v1/media/files/mj_bKAiyenqLjMs9kwfcS4Z5k/0.thumb.webp"
    }
  ],
  "error": null,
  "created_at": "2026-11-04T06:09:38.740Z",
  "started_at": "2026-11-04T06:09:38.762Z",
  "finished_at": "2026-11-04T06:11:05.189Z",
  "queue_timeout_s": null
}

The response above shortens url and thumb_url to their paths and leaves out fields beyond the job object table.

What you can build

Media jobs reference

The job object, the parameters of an image job, ?wait and the model list.

Uploads reference

A PNG, JPEG or WebP image stored as up_…, to start an image to image job from.

Rate limits

The daily processing time of a member account, which image jobs count against.

Key concepts

Image models
GET /v1/media/models?kind=image lists the image models a key may use, each with its parameters, ranges and defaults: zimage-turbo (8 steps by default, takes negative_prompt) and flux-dev (24 steps by default, takes guidance).
Image to image
init_image names an image to start from: an upload up_…, a result of an earlier job of the account as job:<id>/<i>, or an https:// URL. strength sets how far the result departs from the starting image.
Count and seed
count makes 1 to 8 images in one job; image i uses seed + i. Without seed, the job picks one and returns it in params and on each result.
Size
aspect picks one of eight shapes at a fixed size, such as 1344 by 756 pixels at 16:9 and 1024 by 1024 at 1:1; width and height together set an exact size from 512 to 2048 pixels.
Waiting
An image job without priority runs as batch and waits in the queue as long as it takes. ?wait holds a request 85 s at most, so a client reads the job again until state is done, failed, cancelled or expired.
GenAI
The browser app at https://genai.albastov.com makes images and videos for members, with a library, favorites and a public gallery, and single images for signed-out visitors within daily limits.
Media access
An account gets media access, and its keys, from Albastar Corp. at [email protected].

Next steps

Media jobs reference

Every parameter and error of POST /v1/media/jobs.

Authentication

Keys, scopes and how to get a key.

Changelog

Every change to the Albastar API, newest first.