Image-generation provider adapter contract.

Layer B — runtime. Implementations take an ALLM.ImageRequest plus a keyword opts list (resolved at the call site by ALLM.generate_image/3) and return either {:ok, %ALLM.ImageResponse{}} or {:error, %ALLM.Error.ImageAdapterError{}}.

Minimum impl skeleton

defmodule MyImageProvider do
  @behaviour ALLM.ImageAdapter

  @impl true
  def generate(%ALLM.ImageRequest{operation: op} = req, opts) do
    if op in supported_operations do
      # Translate request → HTTP body, fire via Req, translate
      # response → %ALLM.ImageResponse{}.
      {:ok, %ALLM.ImageResponse{}}
    else
      {:error, %ALLM.Error.ImageAdapterError{reason: :unsupported_operation, metadata: %{operation: op}}}
    end
  end

  @impl true
  def supported_operations, do: [:generate]
end

HTTP transport guidance

Use Req for non-streaming image calls. Image generation is a request/response shape — there is no streaming counterpart.

Invariants

1. generate/2 is synchronous: it returns only after the HTTP response has been read in full and any binary image bytes resolved.
2. generate/2 never raises for HTTP-shaped failures. Network failures, 4xx, and 5xx all convert to {:error, %ALLM.Error.ImageAdapterError{reason: ..., ...}}. Only programmer errors (invalid request shape reaching the adapter, which the validator should have caught) may raise.
3. generate/2 MUST honor opts[:request_timeout] if provided. Exceeding the timeout produces {:error, %ImageAdapterError{reason: :timeout}}.
4. generate/2 MUST return {:error, %ImageAdapterError{reason: :unsupported_operation, metadata: %{operation: op}}} BEFORE any HTTP I/O when request.operation not in supported_operations. This is the entry-point gate; per-model gating (e.g., dall-e-3 only supports :generate) is the adapter's internal concern.
5. generate/2 MUST preserve opts[:request_id] onto response.request_id when the response shape allows. When opts[:request_id] is absent, the adapter is free to populate response.request_id from a provider-supplied id (e.g., x-request-id HTTP header).
6. generate/2 MUST round-trip request.metadata onto response.metadata UNCHANGED when the adapter has no use for it. (Library treats request/response metadata as opaque.)
7. prepare_request/2 (optional) returns an unfired Req.Request configured exactly as generate/2 would fire it. Callers may mutate the returned request before firing.