ALLM.ImageRequest (allm v0.6.1)

Copy Markdown View Source

A request for image generation or editing — Layer A serializable data.

Two operations:

  • :generate — text-to-image; requires :prompt, :input_images == [].
  • :edit — modify one or two input images optionally with a :mask; requires :prompt and length(:input_images) in 1..2.

Operation-arity rules are enforced by ALLM.Validate.image_request/1; construction via new/1 does not validate.

See also guides/image_generation.md.

Sizes and qualities

:size accepts {w, h} (positive integers), a binary like "1024x1024", the atom :auto, or nil. JSON encodes the tuple as a 2-element array [w, h]; decode reconstructs the tuple from a 2-element list of positive integers, treats "auto" as :auto, and otherwise passes binaries through verbatim.

:quality is the atom set [:low, :medium, :high, :xhigh, :max, :standard, :hd, :auto] with a String.t open arm — providers extend the set (:hd is dall-e-3-only; :low/:medium/:high are for the GPT image models; :xhigh/:max are gpt-image-2.5-*-only). The decoder restores known atoms; unknown binaries pass through verbatim.

:operation, :response_format, :style, and :background are closed atom enums; an unknown value at decode time raises ArgumentError and surfaces as {:_unknown, :atom_decode_failed} per the serializer's rescue contract. :operation is decoded against its closed set explicitly (not via String.to_existing_atom/1), so a value outside :generate | :edit — including "variation" persisted before v0.6.0 removed that operation — always fails decode, whatever atoms happen to exist in the VM.

Summary

Types

operation()
quality()
response_format()
size()
t()

Functions

new(opts \\ [])

Build an %ImageRequest{} from keyword opts.

Types

operation()

@type operation() :: :generate | :edit

quality()

@type quality() ::
  :low | :medium | :high | :xhigh | :max | :standard | :hd | :auto | String.t()

response_format()

@type response_format() :: :binary | :base64 | :url

size()

@type size() :: {pos_integer(), pos_integer()} | String.t() | :auto

t()

@type t() :: %ALLM.ImageRequest{
  background: :transparent | :opaque | nil,
  input_images: [ALLM.Image.t()],
  mask: ALLM.Image.t() | nil,
  metadata: map(),
  model: String.t() | nil,
  n: pos_integer(),
  operation: operation(),
  options: map(),
  prompt: String.t() | nil,
  quality: quality() | nil,
  response_format: response_format(),
  size: size() | nil,
  style: :natural | :vivid | nil
}

Functions

new(opts \\ [])

@spec new(keyword()) :: t()

Build an %ImageRequest{} from keyword opts.

Unknown keys raise KeyError via struct!/2 (matches ALLM.Request.new/2 precedent). No validation — call ALLM.Validate.image_request/1 to check operation-arity and field rules.

Examples

iex> req = ALLM.ImageRequest.new(prompt: "a kestrel", size: {1024, 1024}, n: 2)
iex> req.operation
:generate
iex> req.size
{1024, 1024}
iex> req.n
2