Generated baml_client

Pdf

Pdf values to BAML functions can be created in client libraries. This document explains how to use these functions both at compile time and runtime to handle Pdf data. For more details, refer to pdf types.

Pdf instances can be created from URLs, Base64 data, or local files. URL processing is controlled by your client’s media_url_handler configuration. Please note that many websites will block requests to directly fetch PDFs.

Some models like Vertex AI require the media type to be explicitly specified. Always provide the mediaType parameter when possible for better compatibility.

The PDF input may need to be put into the user message, not the system message in your prompt.

Usage Examples

1from baml_py import Pdf
2from baml_client import b
3
4async def test_pdf_input():
5    # Create a Pdf object from URL
6    pdf_url = Pdf.from_url("https://example.com/document.pdf")
7    res1 = await b.TestPdfInput(pdf=pdf_url)
8    
9    # Create a Pdf object from Base64 data
10    pdf_b64 = "JVBERi0K..."
11    pdf = Pdf.from_base64(pdf_b64)
12    res2 = await b.TestPdfInput(pdf=pdf)

Test Pdf in the Playground

To test a function that accepts a pdf in the VSCode playground using a local file, add a test block to your .baml file:

1function AnalyzePdf(myPdf: pdf) -> string {
2  client GPT4o
3  prompt #"
4    Summarize this Pdf: {{myPdf}}
5  "#
6}
7
8test PdfFileTest {
9  functions [AnalyzePdf]
10  args {
11    myPdf {
12      file "../documents/report.pdf"
13    }
14  }
15}
file
stringRequired

The path to the PDF file. Supports relative paths (resolved from the current BAML file) or absolute paths. The file does not need to be inside baml_src/.

API Reference

Static Methods

from_url
(url: str) -> Pdf

Creates a Pdf object from a URL. The media type is automatically set to application/pdf.

from_base64
(base64: str) -> Pdf

Creates a Pdf object using Base64 encoded data. The media type is automatically set to application/pdf.

Instance Methods

is_url
() -> bool

Check if the Pdf is stored as a URL.

as_url
() -> str

Get the URL if the Pdf is stored as a URL. Raises an exception if the Pdf is not stored as a URL.

as_base64
() -> list[str]

Get the base64 data and media type if the Pdf is stored as base64. Returns [base64_data, media_type]. Raises an exception if the Pdf is not stored as base64.

baml_serialize
() -> dict

Convert the Pdf to a dictionary representation. Returns either {"url": str} or {"base64": str, "media_type": str}.

URL Handling

PDF URLs are processed according to your client’s media_url_handler configuration:

  • Anthropic: By default converts to base64 (send_base64) as required by their API.
  • AWS Bedrock: By default converts to base64 (send_base64).
  • OpenAI: By default keeps URLs as-is (send_url).
  • Google AI: By default keeps URLs as-is (send_url).
  • Vertex AI: By default keeps URLs as-is (send_url).

Many websites block direct PDF fetching. If you encounter issues with URL-based PDFs, try:

  1. Using media_url_handler.pdf = "send_base64" to fetch and embed the content
  2. Downloading the PDF locally and using from_file
  3. Using a proxy or authenticated request

Configuring Media URL Handlers

You can customize how PDF URLs are processed by configuring the media_url_handler in your BAML client definition. This is useful when you need to override provider defaults or ensure compatibility with specific model requirements.

1// Basic example: OpenAI client with PDF base64 encoding
2client<llm> MyOpenAIClient {
3  provider openai
4  options {
5    model "gpt-4o"
6    api_key env.OPENAI_API_KEY
7    media_url_handler {
8      pdf "send_base64"  // Convert PDF URLs to base64
9    }
10  }
11}
12
13function AnalyzePdf(pdf: pdf) -> string {
14  client MyOpenAIClient
15  prompt #"
16    Analyze this PDF: {{ pdf }}
17  "#
18}

Available Modes

The media_url_handler.pdf setting accepts the following values:

  • send_base64: Fetch the PDF from the URL and convert it to base64 before sending to the model. Use this when the provider requires base64 encoding or when you want to ensure the content is embedded in the request.

  • send_url: Keep the PDF as a URL and send it directly to the model. The model provider will fetch the content. Note that many providers don’t support direct URL fetching for PDFs.

  • send_url_add_mime_type: Keep the PDF as a URL but add MIME type information (application/pdf). Useful for providers like Vertex AI that require explicit MIME types.

  • send_base64_unless_google_url: Keep Google Cloud Storage URLs (gs://) as-is, but convert all other URLs to base64. Useful when working with Google AI models.

Provider-Specific Examples

1// OpenAI: Override default (send_url) to use base64
2client<llm> OpenAIClient {
3  provider openai
4  options {
5    model "gpt-4o"
6    api_key env.OPENAI_API_KEY
7    media_url_handler {
8      pdf "send_base64"  // OpenAI requires base64 for PDFs
9    }
10  }
11}
12
13// Anthropic: Override default (send_base64) to use URL
14client<llm> AnthropicClient {
15  provider anthropic
16  options {
17    model "claude-3-5-sonnet-20241022"
18    api_key env.ANTHROPIC_API_KEY
19    media_url_handler {
20      pdf "send_url"  // Anthropic supports both URL and base64
21    }
22  }
23}
24
25// Vertex AI: Use URL with MIME type
26client<llm> VertexClient {
27  provider vertex-ai
28  options {
29    model "gemini-1.5-pro"
30    project "your-project"
31    location "us-central1"
32    media_url_handler {
33      pdf "send_url_add_mime_type"  // Vertex requires MIME type
34    }
35  }
36}
37
38// Google AI: Use conditional handling for GCS URLs
39client<llm> GoogleAIClient {
40  provider google-ai
41  options {
42    model "gemini-1.5-pro"
43    api_key env.GOOGLE_API_KEY
44    media_url_handler {
45      pdf "send_base64_unless_google_url"  // Keep gs:// URLs, convert others
46    }
47  }
48}
49
50// You can configure multiple media types independently
51client<llm> MultiMediaClient {
52  provider openai
53  options {
54    model "gpt-4o"
55    api_key env.OPENAI_API_KEY
56    media_url_handler {
57      image "send_base64"
58      audio "send_url"
59      pdf "send_base64"
60      video "send_url"
61    }
62  }
63}

You can configure different handling modes for each media type (image, audio, pdf, video) independently in the same client.

Model Compatibility

Different AI models have varying levels of support for PDF input methods (As of July 2025):

Provider / APIPDF Input Support
Anthropic✓Accepts PDFs as a direct https URL or a base‑64 string in a document block.
AWS Bedrock✓PDF must be supplied as raw bytes (base‑64 in the request) or as an Amazon S3 URI (s3:// style). Ordinary https links are not supported.
Google Gemini✓Provide as inline base‑64 or upload first with media.upload and use the returned file_uri. The model does not fetch http/https URLs for you.
OpenAI✓PDF support (added March 2025) via base‑64 in the request. Supplying a plain URL is not accepted.
Google Vertex AI✓Accepts either base‑64 data or a Cloud Storage gs:// URI in a file_data part; you must set mime_type (for PDFs use application/pdf). Generic https URLs are not allowed.

For most models, direct https URLs are not accepted (except Anthropic). Prefer using base64, file uploads, or the appropriate cloud storage/file upload mechanism for your provider. Always specify the correct MIME type (e.g., application/pdf) when required.