@spec create_message_with_images(
  String.t(),
  String.t()
  | {String.t(), String.t()}
  | [String.t() | {String.t(), String.t()}]
  | nil,
  keyword()
) :: map()

Creates a structured message with text and images for vision-based models.

Parameters

• text - The text prompt to include in the message
• images - Optional image(s) to include, can be:
  • A single image (URL string, file path, or {url/path, detail} tuple)
  • A list of images (URL strings, file paths, or {url/path, detail} tuples)
• opts - Options for the message:
  • :detail - Default detail level for all images: "low", "high", or "auto" (default)
  • :role - Message role, defaults to "user"

Image Specification

Images can be specified in several ways:

• URL string: "https://example.com/image.jpg"
• Local file path: "/path/to/image.jpg"
• Tuple with detail level: {"https://example.com/image.jpg", "high"}
• Tuple with detail level: {"/path/to/image.jpg", "low"}

Local image files will be automatically encoded as Base64 data URLs. Supported image formats: .png, .jpeg, .jpg, .webp, .gif

Examples

# Simple text with one image URL
iex> create_message_with_images("What is in this image?", "https://example.com/image.jpg")

# Text with a local image file
iex> create_message_with_images("Describe this image", "/path/to/image.jpg")

# Using high detail for all images
iex> create_message_with_images("Analyze in detail", ["img1.jpg", "img2.jpg"], detail: "high")

# Mixed image sources with specific detail levels
iex> create_message_with_images(
...>   "Compare these", 
...>   [
...>     {"img1.jpg", "low"},
...>     {"https://example.com/img2.jpg", "high"}
...>   ]
...> )

# Text-only message
iex> create_message_with_images("Just a text question")