Image generation

POST /v1/llm/images/jobs returns a job_id in under a second; you poll GET /v1/llm/images/jobs/{job_id} until the status is terminal. Every image slug in the catalog works on the job API — there is no subset to memorise and no model that still needs the synchronous route.

Images are billed per delivered image, not per token, and only when the completion poll returns. A failed or timed-out job costs nothing.

Quick start

POST /v1/llm/images/jobs returns a job_id in under a second, and you poll GET /v1/llm/images/jobs/{job_id} every 2-3 seconds until the status is terminal. You are charged only when the completion poll returns — a timed-out or failed job costs nothing. Server-side, polls that arrive within 2 seconds of each other are coalesced via Redis, so hammering the endpoint will not be billed as repeated upstream calls.

A status: "failed" payload carries a typed error_code — content_moderation (the input was rejected by the upstream content policy; rephrase, don't retry verbatim) or generation_failed (transient; re-kick off). Give the poll loop a 10-minute budget: moderation verdicts and internal retries can land several minutes after kickoff, and abandoning early costs you the render you would have received. Handling recipes: Errors → Image jobs.

import time, requests

BASE = "https://api.gpuniq.com/v1/llm"
HEADERS = {"X-API-Key": "gpuniq_your_key"}

# 1. Kickoff
start = requests.post(
    f"{BASE}/images/jobs",
    headers=HEADERS,
    json={"model": "nano-banana-pro", "prompt": "a cozy cabin at sunrise", "n": 1},
).json()
job_id = start["data"]["job_id"]

# 2. Poll — 10-minute budget: slow 4K renders, moderation verdicts and
#    internal retries can all land several minutes after kickoff
deadline = time.time() + 600
while time.time() < deadline:
    time.sleep(2.5)
    r = requests.get(f"{BASE}/images/jobs/{job_id}", headers=HEADERS).json()
    d = r["data"]
    if d["status"] == "completed":
        image_b64 = d["image"]["b64_json"]
        print(f"Cost: ${d['cost_usd']}, balance: ${d['balance_usd']}")
        break
    if d["status"] == "failed":
        if d.get("error_code") == "content_moderation":
            # Content-policy verdict — retrying the same prompt will fail
            # again. Rephrase (drop video-style wording: durations,
            # camera moves) and kick off a new job.
            print("rejected by content policy:", d.get("error"))
        else:
            # generation_failed — transient; safe to re-kick off.
            print("failed:", d.get("error"))
        break

Parameters

Models & pricing

Image models are billed per returned image, not per token.

How size picks the GPT Image 2 tier (and the price). The size field accepts WIDTHxHEIGHT or a bare 1k / 2k / 4k. The tier is chosen by a ceiling rule on the long side — the delivered image is never smaller than the ask: up to 1024px → base gpt-image-2 ($0.0464), up to 2048px → the 2K tier ($0.07), above 2048px → the 4K tier ($0.11). The response's usage.model (sync) / model (job) names the tier you were billed for, and the kickoff's estimated_cost_usd reflects it up front. Aspect ratio follows your size proportions — wide and tall formats including 21:9 and 3:2 are honoured, with or without reference images.

Nano Banana Pro upgrades by pixel budget, not by long side — banana tiers scale output with the aspect ratio (the 2K tier at 16:9 renders 2752×1536), so a QHD 2560x1440 ask stays on the base Pro ($0.1072) and comes back at 2752×1536. Only asks beyond the 2K budget (more than ~4.2 MP, or wider than 3168px) auto-upgrade to nano-banana-pro-4k ($0.192).

GPT Image 2 2K/4K renders now return the exact width×height you asked for (up to a 3840px long side; larger asks scale down proportionally, e.g. 4096×4096 → 3840×3840) and typically complete in 40–80 seconds. If the primary route rejects a request, GPUniq retries on an alternate 2K/4K route automatically; if the content itself is rejected everywhere, the request degrades once to the base gpt-image-2 at the base price ($0.0464, ~1.6K render) — the response's model field always names the SKU you were billed for.

Nano Banana 4K output dimensions depend on the aspect ratio — the tier fixes the pixel budget, not the long side, so wide formats come back wider than 4096px. Expect these dimensions from the 4K tier (nano-banana-pro-4k, nano-banana-2 at 4K):

4K renders on this family take noticeably longer than 1K/2K — 2–5 minutes is normal, which is another reason to keep the job polling budget at 10 minutes.

Midjourney

Midjourney works differently from every other model here, because Midjourney itself has no public API: a render is a job on a real Midjourney account, and the unit of work is a grid, not a picture.

One mj_imagine call buys one Midjourney job: four concepts, for $0.16. You normally receive them as four separate full-size frames (1456×816 at 16:9) — not a grid you have to crop. Billing is per job, never per frame, so four images cost exactly the same as one. Renders take 55–95 seconds, so use the job API.

Every delivered Midjourney image carries an mj_task_id. Pass it back with mj_index (1–4, reading order — 1 is top-left) to run an action on that frame:

# 1. The render — four concepts, one charge
job = requests.post(f"{BASE}/v1/llm/images/jobs", headers=H, json={
    "model": "mj_imagine",
    "prompt": "an owl librarian in a candlelit archive",
    "size": "16:9",          # or 1920x1080 — becomes Midjourney's --ar
}).json()["data"]
# ... poll GET /v1/llm/images/jobs/{job_id} until status == "completed"

# 2. More like frame 2, please
requests.post(f"{BASE}/v1/llm/images/jobs", headers=H, json={
    "model": "mj_variation",
    "mj_task_id": done["image"]["mj_task_id"],
    "mj_index": 2,                      # no prompt needed for actions
})

mj_variation returns a fresh set of four concepts built from the frame you picked — same price as an imagine, because it is the same amount of work.

Notes worth knowing before you build on it:

• size is an aspect ratio, not a resolution. 16:9, 3:2 and 1920x1080 all work; the ratio is what reaches Midjourney (--ar). Output resolution is Midjourney's own.
• You get Midjourney v8.2 by default — the newest line. Relays default to v7 if nobody asks, so we ask. Pin another with a version flag in the prompt (--v 6.1, --niji 7) and yours wins.
• Midjourney parameters pass through the prompt. Anything you write as --stylize 750, --chaos 20, --niji 6 and so on is honoured; an --ar you write yourself wins over size.
• Reference images work via input_images (https URLs or data URLs).
• mj_task_id is opaque and route-bound. Store it as a string and pass it back unchanged; upscales and variations run where the grid lives, so a handle from one render is not valid for another.
• A rejected prompt is final. Midjourney's content filter is Midjourney's own — a 400 comes back immediately rather than being retried elsewhere, so rephrase rather than retrying verbatim.

Generating an image inside a chat session

When you want the image to appear as a turn in an existing chat (so the prompt and result both land in the chat history), POST to /v1/llm/chats/{chat_id}/messages with an image model. The response returns immediately with type: "image_pending" plus a job_id and the dialogue_id of a placeholder row that already lives in the chat history. Poll GET /v1/llm/chats/{chat_id}/image-jobs/{job_id} until the status is completed (placeholder is rewritten with the image and the balance is debited) or failed (placeholder is marked, nothing charged). The polling endpoint 404s once the job is terminal — the final dialogue is the source of truth from then on.

import time, requests

BASE = "https://api.gpuniq.com/v1/llm"
HEADERS = {"X-API-Key": "gpuniq_your_key"}
chat_id = 42  # existing chat created via POST /v1/llm/chats

# 1. Kickoff (POST /chats/{id}/messages with an image model)
start = requests.post(
    f"{BASE}/chats/{chat_id}/messages",
    headers=HEADERS,
    json={"model": "nano-banana-pro", "message": "a cozy cabin at sunrise"},
).json()
job_id = start["data"]["job_id"]
dialogue_id = start["data"]["dialogue_id"]

# 2. Poll — same 5-minute budget as the standalone /images/jobs flow
deadline = time.time() + 300
while time.time() < deadline:
    time.sleep(2.5)
    r = requests.get(
        f"{BASE}/chats/{chat_id}/image-jobs/{job_id}", headers=HEADERS,
    ).json()
    d = r["data"]
    if d["status"] == "completed":
        image_b64 = d["image"]["b64_json"]
        print(f"Cost: ${d['cost_usd']}, balance: ${d['balance_usd']}")
        break
    if d["status"] == "failed":
        print("failed:", d.get("error"))
        break

Use this surface when the image should be part of a multi-turn conversation. Use the standalone /images/jobs surface when you don't need persistence — it has the same job semantics without creating a chat row.

Which endpoint serves which slug

Every image slug in the catalog works on the job API. There is no subset to memorise and no reason to keep a synchronous code path around: if the model is in the table above, POST /v1/llm/images/jobs accepts it.

n must be 1 — issue separate jobs in parallel for batches. (Topaz upscaling/enhancement has its own dedicated job surface — see the Topaz guide.)

Behind the job id there are two execution modes, and the difference is not visible in the API contract — same kickoff, same polling, same response shape:

The second mode runs the same multi-tier provider cascade the synchronous endpoint uses, so failover, moderation verdicts and format conversion all behave identically. You are still charged only on delivery.

Video has no synchronous endpoint at all. Every video generation goes through POST /v1/llm/videos/jobs — there is nothing to migrate and no sync variant to find.

The legacy synchronous endpoint

Both API surfaces expose a /images/generations endpoint that matches OpenAI's images.generate protocol. Pass any image slug from the catalog above (e.g. nano-banana-pro, gpt-image-2, flux-2-pro, seedream-4). Billing is flat per returned image — no token accounting.

Image requests route through a multi-tier reliability chain behind the scenes: a per-model priority gateway, two cost-optimised intermediaries, then a generic OpenAI-compatible fallback for safety. The chain is selected automatically per slug, so SDK callers never pick a backend themselves. If the primary fails or returns no image, the next tier is tried within the same HTTP request — you still see one synchronous POST /images/generations and pay for delivered images only.

Heavy generations (Pro / 4K, multi-image batches, high-quality preset) can run up to 5 minutes end-to-end; the connection is held open for that whole budget so SDKs never need to re-poll.

from openai import OpenAI

client = OpenAI(
    api_key="gpuniq_your_key",
    base_url="https://api.gpuniq.com/v1/openai",
)

resp = client.images.generate(
    model="nano-banana-pro",
    prompt="A cozy mountain cabin at sunrise, cinematic lighting",
    n=2,
    size="1024x1024",
    response_format="b64_json",
)

for i, img in enumerate(resp.data):
    with open(f"out_{i}.png", "wb") as f:
        import base64
        f.write(base64.b64decode(img.b64_json))

import base64, requests

with open("reference.jpg", "rb") as fh:
    ref = "data:image/jpeg;base64," + base64.b64encode(fh.read()).decode()

resp = requests.post(
    "https://api.gpuniq.com/v1/llm/images/generations",
    headers={"X-API-Key": "gpuniq_your_key"},
    json={
        "model": "nano-banana-pro",
        "prompt": "Redraw the cabin in watercolor style",
        "n": 1,
        "size": "2048x2048",
        "input_images": [ref],
    },
).json()

print("cost:", resp["data"]["cost_usd"])

curl -X POST https://api.gpuniq.com/v1/openai/images/generations \
  -H "Authorization: Bearer gpuniq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4-image",
    "prompt": "Studio portrait of an astronaut in a pink desert",
    "n": 1,
    "size": "1024x1024"
  }'