image_gen (service)

Text-to-image generation via OpenAI's GPT Image 2. A .service asset — a plain Luau module, resolvable as @builtin::services.image_gen, exposing a generator that runs through the credit-metered service path.

Operations

• generate({ prompt, size?, quality?, quiet? }): text-to-image. size is a WIDTHxHEIGHT in pixels ('1024x1024', '1536x1024', '1024x1536', '2560x1440', ...) with both edges multiples of 16, neither edge over 3840, the long edge at most 3 times the short one and 655360 to 8294400 pixels in all, or explicit 'auto' to let the model choose from the prompt; quality is 'low' (the default) or 'high'. High selects the provider's medium quality; the active gateway determines its price. Legacy 'medium' selects high and legacy 'auto' selects low. Any other value is refused at the call, naming what the input takes. The image comes back inline as base64 and is written under /zero/source/generated/images/. By default the raw PNG is imported into a spawnable .texture asset; pass quiet = true to write the raw PNG only, without the import.

Using it

local image = asset.resolve("image_gen", "service")
print(image:cost("generate", { prompt = "a mossy stone idol", quality = "low" }), image:balance())          -- budget before spending
local g = image:invoke({ prompt = "a mossy stone idol" })

-- Watch the run until it settles; a completed row's `asset` is the finished,
-- spawnable `.texture`.
local row = tools.use("services", "status", { id = g.id })
while row ~= nil and row.status ~= "completed" and row.status ~= "failed" do
    task.wait(1)
    row = tools.use("services", "status", { id = g.id })
end
print(row.status, row.asset)

The handle's asset_path is where the run directs the raw generated file; the asset it becomes is the completed status row's asset, which is what to spawn.

Cost

services.list() and Inspector show "Price available after required options". :cost("generate", { prompt = "a tree", size = "1024x1024", quality = "high" }) reads the current complete-input price. It does not reserve or accept it. Pass that amount as max_credits to generation to retain your accepted ceiling; a higher fresh quote is refused. Without a ceiling, generation authorizes its current quote and reports quotedCredits and maxCredits on its handle.

The descriptor prefers origozero/image_gen_v2. If the offering or quote capability is absent, it uses origozero/image_gen with explicit low/medium. A quote-capable gateway quotes the legacy price and enforces its ceiling. Older gateways retain their unquoted contract: no quoted amount is claimed, :cost() explains that quotes are unavailable, and an explicit max_credits is refused. Other failures do not trigger fallback. The selected route and ceiling survive task resume. Older clients still need the separately approved legacy registration update to change their pricing/quality.

Custom sizes

All valid custom WIDTHxHEIGHT sizes remain available: multiples of 16, each edge at most 3840, aspect ratio at most 3, and 655360–8294400 pixels inclusive. Omitted size uses 1024x1024. Explicit auto remains provider-selected; a quote states the internal credit price, not the output dimensions or provider cost.