ALLM.ImageRequest (allm v0.3.0)

Copy Markdown View Source

A request for image generation, editing, or variation. See spec §35.2.2.

Layer A — pure serializable data. Three 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.
  • :variation — generate variants of one input image; requires length(:input_images) == 1 and :prompt in [nil, ""].

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

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 closed atom set [:low, :standard, :high, :hd, :auto] with a String.t() open arm — providers extend the set (:hd is dall-e-3-only; :high is gpt-image-1-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.

Summary

Types

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

Functions

new(opts \\ [])

Build an %ImageRequest{} from keyword opts.

Types

operation()

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

quality()

@type quality() :: :low | :standard | :high | :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