OpenAI Images provider adapter — implements ALLM.ImageAdapter against OpenAI's /v1/images/generations, /v1/images/edits, and /v1/images/variations endpoints. See spec §35.7.

Layer B — runtime. Constructed via ALLM.Engine.new(image_adapter: ALLM.Providers.OpenAI.Images, model: "dall-e-2") and consumed through the ALLM.generate_image/3 · edit_image/4 · image_variations/3 façade (Phase 14.2). Keys resolve via ALLM.Keys.fetch!(:openai, opts) at request-build time per spec §6.4 — no key ever lives on the engine.

Status

The JSON :generate HTTP path is wired for dall-e-2, dall-e-3, and gpt-image-1. The gpt-image-1 path applies forced-base64 normalization (gpt-image-1 ignores response_format at the wire), token-based usage (input_tokens / output_tokens), and output_format → :mime_type mapping per Decision #19. The multipart :edit HTTP path is wired for dall-e-2 and gpt-image-1, including URL-source eager-download per Decision #8. The :variation path is wired for dall-e-2 via the same multipart machinery as :edit — variation drops prompt and mask fields and otherwise mirrors :edit's wire shape.

Model × Operation matrix

Cells marked "no" produce {:error, %ImageAdapterError{reason: :unsupported_operation, metadata: %{operation: op, model: model}}} BEFORE any HTTP I/O. Unknown models (any string not in the matrix) fall through to the provider — see Decision #3 of steering/PHASE_15_image_layer_6.md.

gpt-image-1 specifics

• Body fields. When request.model == "gpt-image-1", to_json_body/2 OMITS response_format, includes quality / background per the wire-field map, and includes output_format from request.options[:output_format] ("png" | "jpeg" | "webp"). When :output_format is absent the adapter OMITS the field and the OpenAI API applies its server-side default of "png". Per CLAUDE.md "Adapters MUST document any default they inject for a Layer-A nil field that the wire requires" — gpt-image-1's output_format does NOT need an adapter-side default because the provider-default and the project's response :mime_type default both resolve to PNG.
• Response decode. gpt-image-1 always returns b64_json per image. For :binary callers the adapter Base64-decodes server-side; for :base64 callers the b64 is forwarded verbatim. :url callers are rejected pre-flight (Decision #6).
• Response :mime_type. Driven by request.options[:output_format] via mime_type_for_output_format/1: "png"|:png → "image/png", "jpeg"|:jpeg|:jpg → "image/jpeg", "webp"|:webp → "image/webp", absent → "image/png".
• Token usage. ImageUsage.input_tokens / output_tokens from body.usage; ImageUsage.images = length(data) as elsewhere. body.usage.input_tokens_details (when present) lands on response.metadata[:usage_details] without overwriting caller keys.

Multipart vs JSON dispatch (Decision #7)

The :generate operation uses an application/json body via Req.new(json: ...) and OpenAIHeaders.json_headers/2. The :edit and :variation operations require an actual image upload, so they use multipart/form-data via Req.new(form_multipart: ...) and OpenAIHeaders.multipart_headers/2 (which elides content-type so Req's :form_multipart step stamps it with the boundary).

Both paths flow through the same Retry.run/3 integration and share the same decode_response/4 and to_image_adapter_error/4 helpers — the response shape is identical to :generate (a data: [...] array of url/b64_json items, optional usage on gpt-image-1).

URL-source resolution (Decision #8)

:edit / :variation requests carrying Image.from_url/1 images are eagerly fetched at request-build time. The Req.get/2 call honors a 30 s default receive_timeout (override via opts[:request_timeout]), a 5-redirect cap, and a 25 MB body-size cap. Failure modes (closed):

• Non-2xx HTTP status → :invalid_request with metadata: %{url: u, status: status}.
• Non-image content-type (must prefix-match ~r{^image/(png|jpeg|jpg|webp|gif)$}) → :invalid_request with metadata: %{url: u, content_type: ct}.
• Body > 25 MB → :invalid_request with metadata: %{url: u, size: bytes}.
• More than 5 redirects (Req.TooManyRedirectsError) → :invalid_request with metadata: %{url: u}.
• Timeout / network error (Req.TransportError, etc.) → :network_error with metadata: %{url: u} and the underlying exception on :cause.

URL fetches are stubbable in tests via Req.Test.stub/2; pass the same adapter_opts: [plug: {Req.Test, stub}] used for the API stub and the fetch will route through the stub.

Test-injection escape hatch

Per Decision #20, generate/2 honors opts[:adapter_opts][:image_script] as a documented test-only short- circuit: when present, the call delegates to ALLM.Providers.FakeImages.generate/2 BEFORE any pre-flight gate runs and returns its result verbatim. This is the same pattern ALLM.Test.ImageAdapterConformance uses to script adapters under test. Production callers do not populate this key.

Retry integration

HTTP error closures return {:retry, delay_ms, error} for 429 + Retry-After, 5xx, and timeouts; ALLM.Retry.run/3 is wired against the engine's policy. Phase 14.3 augmented the retry vocabulary with the four image-error atoms (:rate_limited, :provider_unavailable, :timeout, :network_error) at the façade call site.

URL-mode expiry warning

Per Decision #5, OpenAI documents that image URLs returned via response_format: :url expire ~60 minutes after creation. Callers persisting Image{source: {:url, _}} beyond that window should download the bytes themselves before persisting, or request :base64 / :binary upfront. The adapter does NOT proactively materialize URL-mode responses to bytes.

Closed-enum mapping table caveat

:context_length_exceeded is reserved in ImageAdapterError's closed enum but is NOT actively mapped — long-prompt rejections from OpenAI surface as :invalid_request per Decision #21. :unsupported_feature is not produced by this adapter (Decision #22).