# `ReqLLM.Images`
[🔗](https://github.com/agentjido/req_llm/blob/main/lib/req_llm/images.ex#L1)

Image generation functionality for ReqLLM.

This module provides image generation capabilities with support for:
- Prompt-based image generation (`generate_image/3`)
- Streaming generation with preview frames (`stream_image/3`, OpenAI and
  Azure gpt-image models)
- Model validation for image support
- The full gpt-image parameter set on OpenAI and Azure: quality tiers,
  `:background`, `:moderation`, `:output_compression`, and `:input_fidelity`
  (see `schema/0` for the per-option rules)

Image results are returned as canonical `ReqLLM.Response` structs where the
assistant message contains `ReqLLM.Message.ContentPart` entries of type
`:image` and/or `:image_url`.

# `drop_openai_only_options`

```elixir
@spec drop_openai_only_options(keyword(), String.t()) :: {keyword(), [String.t()]}
```

Drops the options only the OpenAI Images wire format has fields for.

`:background`, `:moderation`, `:output_compression`, and `:input_fidelity` are
part of this shared schema, so every provider's image path accepts them. A
provider whose endpoint has no such field must drop them in its
`c:ReqLLM.Provider.translate_options/3` image clause: an option that survives
translation reaches the Req pipeline unregistered and raises there, instead of
surfacing through `:on_unsupported` like any other lossy translation.

Returns `{opts, warnings}`, with `provider_label` naming the provider in each
warning.

# `generate_image`

```elixir
@spec generate_image(
  ReqLLM.model_input(),
  String.t() | list() | ReqLLM.Context.t(),
  keyword()
) ::
  {:ok, ReqLLM.Response.t()} | {:error, term()}
```

Generates images using an AI model with full response metadata.

Returns a canonical `ReqLLM.Response` where images are represented as message content parts.

# `schema`

```elixir
@spec schema() :: NimbleOptions.t()
```

Returns the base image generation options schema.

# `stream_image`

```elixir
@spec stream_image(
  ReqLLM.model_input(),
  String.t() | list() | ReqLLM.Context.t(),
  keyword()
) ::
  {:ok, ReqLLM.StreamResponse.t()} | {:error, term()}
```

Streams image generation, yielding preview frames before the final image.

See `ReqLLM.stream_image/3` for the chunk contract. Supported for OpenAI and
Azure gpt-image models; other providers return `ReqLLM.Error.Invalid.Parameter`.

# `stream_image!`

```elixir
@spec stream_image!(
  ReqLLM.model_input(),
  String.t() | list() | ReqLLM.Context.t(),
  keyword()
) ::
  ReqLLM.StreamResponse.t() | no_return()
```

Streams image generation, raising on error.

Same as `stream_image/3` but raises the error struct instead of returning
`{:error, error}`. Only errors raised before the request starts are surfaced
here; failures mid-stream still surface while enumerating or through
`ReqLLM.StreamResponse.to_response/1`.

# `supported_models`

```elixir
@spec supported_models() :: [String.t()]
```

Returns a list of model specs that likely support image generation.

Uses capability metadata when present, otherwise falls back to a conservative
name-based heuristic (models containing "image" or "imagen").

# `validate_model`

```elixir
@spec validate_model(ReqLLM.model_input()) ::
  {:ok, LLMDB.Model.t()} | {:error, term()}
```

Validates that a model supports image generation operations.

---

*Consult [api-reference.md](api-reference.md) for complete listing*