# Image generation The `imagegen` extension exposes a shared Python interface for generating and editing raster images. Driver extensions contribute `ImagegenPlugin` providers. Codex supplies the built-in driver through ChatGPT sign-in. The shared interface and the driver can be enabled independently. [`extensions/imagegen/extension.gleam`](../src/albedo/harness/extensions/imagegen/extension.gleam) owns host routes, driver selection, reference resolution, and response bounds. [`imagegen.py`](../priv/python/albedo_plugins/imagegen.py) owns local reference reads and output publication. See [plugins](plugins.md#image-generation-drivers) for the driver contract. ## Select a driver `await imagegen.providers()` returns the loaded drivers' names and labels. `await imagegen.generate(prompt, provider=...)` selects one by name. Omitting `provider` works only when exactly one driver is active. An absent or ambiguous selection fails without trying another driver. Reloading extensions updates the drivers captured for later host calls. Driver discovery does not establish that an account is signed in or that the upstream service accepts its request. Codex selects credentials in the daemon through the existing [account selection](auth.md) interface. Its [configuration](../src/albedo/harness/extensions/codex/imagegen_config.gleam) owns the image model setting separately from the reasoning model. Its configured default is `gpt-image-2`; this is not a model-availability guarantee. The production endpoint is fixed to `https://chatgpt.com/backend-api/codex`, and the transport refuses other destinations and does not follow redirects. Do not forward subscription credentials to an arbitrary image service. ## Generate and inspect The Python call is: ```python result = await imagegen.generate( "A cut-paper illustration of a fox in snow", transparent_background=True, output="output/imagegen/fox.png", ) show_image(result.path) ``` The result contains `path`, `mime_type`, `width`, `height`, `bytes`, `request_id`, and `generation_id`. Without an output path, the binding chooses `output/imagegen/generated-.png` in the kernel's working directory. Output must be PNG and at most 5 MiB. Existing files and dangling output symlinks are refused. Publication uses a same-directory hard link to avoid replacing a destination created during generation. Generating a file does not attach it to the conversation. `show_image` is a separate operation subject to the active reasoning model's viewing limits. Read the [shipped image generation guidance](../priv/skills/imagegen/SKILL.md) for reference selection, prompting, inspection, and revisions. That skill grants no additional tools or permission to spend quota. ## Reference images Pass at most five references to `imagegen.generate(..., references=[...])`. Local PNG, JPEG, and WebP files must total at most 5 MiB. The binding reads only regular files, checks the image bytes, and sends inline data to the daemon. `await imagegen.references(after=0, limit=50)` discovers uploaded and tool-output images in the current session. Each entry includes a `reference` identifier, transcript sequence, image index, MIME type, width, and height. Pass the returned identifier to `generate`; do not invent identifiers or reuse another session's. The daemon resolves each identifier against the calling session and checks its stored image bytes. Each transcript reference is limited to 5 MiB. Pages scan transcript rows, including rows without images. Continue with `next_after` while `has_more` is true, even when `images` is empty. The page limit is between 1 and 100 rows. Local references and transcript identifiers can be mixed, and their order is preserved. ## Cancellation and recovery Generation can consume quota or incur provider charges. Do not automatically retry an interrupted, cancelled, or uncertain call, and do not change drivers as a fallback. Re-running the Python expression creates a new call identity and can submit another request. The admission map is not durable idempotency. [`imagegen/calls`](../src/albedo/harness/extensions/imagegen/calls.gleam) owns bounded admission and cancellable workers. The kernel's existing [host-call ledger](kernel.md#session-layer) owns replay decisions across reattachment. A worker ending locally cannot undo an already submitted upstream generation. The extension's `StartupPlugin` starts one admission for the daemon's store and returns the `OwnedManagedPlugin` whose `imagegen` routes close over that opaque `calls.Admission`. Nothing finds the admission by name. Closing the store stops it. Each prepared composition takes a `calls.Lease` on its session, which the runtime adopts and closes with the composition. `imagegen.begin` admits a call ID for the calling session and parks a coordinator for it. The admission holds at most eight calls for one session and 512 in total across the daemon. A begin for a session that no lease holds is refused. A parked coordinator gives up its slot after one minute. `imagegen.generate` claims the parked coordinator once as an opaque `calls.Call` and runs the driver in that coordinator's linked worker. A missing, repeated, cancelled, or expired begin is refused, and the call must not be replayed. The caller, the coordinator, or the admission ending stops the worker and reports an uncertain outcome. A request has 600 seconds before the coordinator reports the deadline. A call belongs to its session, not to the composition that admitted it. An extension reload that keeps image generation prepares the replacement composition, and its lease, before it closes the previous one. A running call therefore survives the reload, including one awaited by a backgrounded cell. Cancellation through the replacement composition's routes reaches it. When a session's last lease ends, the admission stops that session's calls with the uncertain "admission owner ended" outcome. Closing that lease returns once their coordinators have stopped, waiting at most five seconds for each. Removing image generation from a session and deleting the session both end its last lease. Removing image generation also changes the kernel's Python modules, so that reload is refused while a cell is running and otherwise replaces the kernel. Stopping the daemon closes the store, which stops the admission, and every coordinator then stops its worker with the same outcome. Successful cancellation waits for the coordinator and request worker to stop before releasing their slot. It does not establish whether the upstream service accepted the request before the worker stopped. The binding probes the destination before contacting the provider and validates the returned image before publication. A later storage error can leave complete bytes in a `.imagegen-*.png` temporary file. Inspect the reported recovery path and the destination before generating again. A retained copy does not establish that its bytes reached durable storage. Partial output must not be reported as a complete image. Host and driver refusals raise `ImagegenError`. Local validation and filesystem failures raise Python exceptions. Preserve request identifiers when reporting an uncertain outcome. [Provider request accounting](provider-requests.md#image-generation) has a separate limitation for these calls. ## Related pages - [All topics](README.md) - [Plugins](plugins.md) - [Model authentication](auth.md) - [Models catalog](models.md) - [Kernel](kernel.md) - [Skills](skills.md)