Media Url Handler

media_url_handler

Controls how media URLs are processed before sending to the provider. This allows you to override the default behavior for handling images, audio, PDFs, and videos.

client<llm> MyClient {
  provider openai
  options {
    media_url_handler {
      image "send_base64"                    // Options: send_base64 | send_url | send_url_add_mime_type | send_base64_unless_google_url
      audio "send_url"
      pdf "send_url_add_mime_type"
      video "send_url"
    }
  }
}

Options

Each media type can be configured with one of these modes:

• send_base64 - Always download URLs and convert to base64 data URIs
• send_url - Pass URLs through unchanged to the provider
• send_url_add_mime_type - Ensure MIME type is present (may require downloading to detect)
• send_base64_unless_google_url - Only process non-gs:// URLs (keep Google Cloud Storage URLs as-is)

Provider Defaults

If not specified, each provider uses these defaults:

When to Use

• Use send_base64 when your provider doesn't support external URLs and you need to embed media content
• Use send_url when your provider handles URL fetching and you want to avoid the overhead of base64 conversion
• Use send_url_add_mime_type when your provider requires MIME type information (e.g., Vertex AI)
• Use send_base64_unless_google_url when working with Google Cloud Storage and want to preserve gs:// URLs