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.jsonPython
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:
{
"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=imagelists the image models a key may use, each with its parameters, ranges and defaults:zimage-turbo(8 steps by default, takesnegative_prompt) andflux-dev(24 steps by default, takesguidance).- Image to image
init_imagenames an image to start from: an uploadup_…, a result of an earlier job of the account asjob:<id>/<i>, or anhttps://URL.strengthsets how far the result departs from the starting image.- Count and seed
countmakes 1 to 8 images in one job; imageiusesseed+i. Withoutseed, the job picks one and returns it inparamsand on each result.- Size
aspectpicks one of eight shapes at a fixed size, such as 1344 by 756 pixels at16:9and 1024 by 1024 at1:1;widthandheighttogether set an exact size from 512 to 2048 pixels.- Waiting
- An image job without
priorityruns asbatchand waits in the queue as long as it takes.?waitholds a request 85 s at most, so a client reads the job again untilstateisdone,failed,cancelledorexpired. - GenAI
- The browser app at
https://genai.albastov.commakes 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.