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.

Usage Examples

async def test_pdf_input(): # Create a Pdf object from URL pdf_url = Pdf.from_url("https://example.com/document.pdf") res1 = await b.TestPdfInput(pdf=pdf_url)

# Create a Pdf object from Base64 data
pdf_b64 = "JVBERi0K..."
pdf = Pdf.from_base64(pdf_b64)
res2 = await b.TestPdfInput(pdf=pdf)

```typescript
import { b } from '../baml_client'
import { Pdf } from "@boundaryml/baml"

// Create a Pdf object from URL
const pdfUrl = Pdf.fromUrl('https://example.com/document.pdf')
const res1 = await b.TestPdfInput(pdfUrl)

// Create a Pdf object from Base64 data
const pdf_b64 = "JVBERi0K..."
const res2 = await b.TestPdfInput(
  Pdf.fromBase64(pdf_b64)
)

// Browser-specific helpers
const filePdf = await Pdf.fromFile(file)
const blobPdf = await Pdf.fromBlob(blob)

import { useTestPdfInput } from '../baml_client/react/hooks'
import { Pdf } from "../baml_client/react/media"

export function TestPdfInput() {
    const { mutate } = useTestPdfInput()

    const handleClick = async () => {
        // Using URL
        const pdfUrl = Pdf.fromUrl('https://example.com/document.pdf')
        mutate(pdfUrl)
        
        // Or using Base64
        const pdf_b64 = "JVBERi0K..."
        const pdf = Pdf.fromBase64(pdf_b64)
        mutate(pdf)
    }

    return (
      <div>
          <button onClick={handleClick}>
              Test Pdf Input
          </button>
      </div>
    )
}

package main

import (
    "context"
    
    b "example.com/myproject/baml_client"
)

func testPdfInput() error {
    ctx := context.Background()
    
    // Create a PDF object from URL
    pdfUrl, err := b.NewPDFFromUrl("https://example.com/document.pdf", nil)
    if err != nil {
        return err
    }
    
    result1, err := b.TestPdfInput(ctx, pdfUrl)
    if err != nil {
        return err
    }
    
    // Create a PDF object from Base64 data
    pdfB64 := "JVBERi0K..."
    pdf, err := b.NewPDFFromBase64(pdfB64, nil)
    if err != nil {
        return err
    }
    
    result2, err := b.TestPdfInput(ctx, pdf)
    if err != nil {
        return err
    }
    
    return nil
}

use myproject::baml_client::sync_client::B;
use myproject::baml_client::new_pdf_from_base64;

fn test_pdf_input() {
    // Create a PDF from Base64 data
    let b64 = "JVBERi0K....";
    let pdf = new_pdf_from_base64(b64, None);
    let res = B.TestPdfInput.call(&pdf).unwrap();
}

# Ruby implementation is in development.

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:

function AnalyzePdf(myPdf: pdf) -> string {
  client GPT4o
  prompt #"
    Summarize this Pdf: {{myPdf}}
  "#
}

test PdfFileTest {
  functions [AnalyzePdf]
  args {
    myPdf {
      file "../documents/report.pdf"
    }
  }
}

API Reference

Static Methods

<ParamField path="from_url" type="(url: str) -> Pdf"

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

<ParamField path="from_base64" type="(base64: str) -> Pdf"

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

Instance Methods

<ParamField path="is_url" type="() -> bool"

Check if the Pdf is stored as a URL. </ParamField>

<ParamField path="as_url" type="() -> str"

Get the URL if the Pdf is stored as a URL. Raises an exception if the Pdf is not stored as a URL. </ParamField>

<ParamField path="as_base64" type="() -> 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. </ParamField>

<ParamField path="baml_serialize" type="() -> dict"

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

Static Methods

<ParamField path="fromUrl" type="(url: string, mediaType?: string) => Pdf"

Creates a Pdf object from a URL. The mediaType parameter is optional but recommended for better model compatibility. If not provided, the media type will be inferred when the content is fetched. </ParamField>

<ParamField path="fromBase64" type="(base64: string) => Pdf"

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

<ParamField path="fromFile" type="(file: File) => Promise<Pdf>"

<Info>Only available in browser environments. @boundaryml/baml/browser</Info> Creates a Pdf object from a File object. Available in browser environments only. </ParamField>

<ParamField path="fromBlob" type="(blob: Blob, mediaType?: string) => Promise<Pdf>"

<Info>Only available in browser environments. @boundaryml/baml/browser</Info> Creates a Pdf object from a Blob object. Available in browser environments only. </ParamField>

Instance Methods

<ParamField path="isUrl" type="() => boolean"

Check if the Pdf is stored as a URL. </ParamField>

<ParamField path="asUrl" type="() => string"

Get the URL if the Pdf is stored as a URL. Throws an Error if the Pdf is not stored as a URL. </ParamField>

<ParamField path="asBase64" type="() => [string, string]"

Get the base64 data and media type if the Pdf is stored as base64. Returns [base64Data, mediaType]. Throws an Error if the Pdf is not stored as base64. </ParamField>

<ParamField path="toJSON" type="() => { url: string } | { base64: string; media_type: string }"

Convert the Pdf to a JSON representation. Returns either a URL object or a base64 object with media type, depending on how the Pdf was created. </ParamField>

Static Methods

<ParamField path="NewPDFFromUrl" type="(url string, mediaType *string) (*PDF, error)"

Creates a PDF object from a URL. Optionally specify the media type for better model compatibility. </ParamField>

<ParamField path="NewPDFFromBase64" type="(base64 string, mediaType *string) (*PDF, error)"

Creates a PDF object using Base64 encoded data. The media type is automatically set to application/pdf if not provided. </ParamField>

Instance Methods

<ParamField path="IsUrl" type="() bool"

Check if the PDF is stored as a URL. </ParamField>

<ParamField path="AsUrl" type="() (string, error)"

Get the URL if the PDF is stored as a URL. Returns an error if the PDF is not stored as a URL. </ParamField>

<ParamField path="AsBase64" type="() (string, string, error)"

Get the base64 data and media type if the PDF is stored as base64. Returns (base64Data, mediaType, error). Returns an error if the PDF is not stored as base64. </ParamField>

<ParamField path="ToJSON" type="() (map[string]interface{}, error)"

Convert the PDF to a map representation. Returns either {"url": string} or {"base64": string, "media_type": string}. </ParamField>

Static Methods

<ParamField path="new_pdf_from_base64" type="(base64: &str, media_type: Option<&str>) -> BamlPdf"

Creates a PDF from Base64 encoded data. The media type defaults to application/pdf. </ParamField>

Ruby implementation is in development.

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).

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.

// Basic example: OpenAI client with PDF base64 encoding
client<llm> MyOpenAIClient {
  provider openai
  options {
    model "gpt-4o"
    api_key env.OPENAI_API_KEY
    media_url_handler {
      pdf "send_base64"  // Convert PDF URLs to base64
    }
  }
}

function AnalyzePdf(pdf: pdf) -> string {
  client MyOpenAIClient
  prompt #"
    Analyze this PDF: {{ pdf }}
  "#
}

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

// OpenAI: Override default (send_url) to use base64
client<llm> OpenAIClient {
  provider openai
  options {
    model "gpt-4o"
    api_key env.OPENAI_API_KEY
    media_url_handler {
      pdf "send_base64"  // OpenAI requires base64 for PDFs
    }
  }
}

// Anthropic: Override default (send_base64) to use URL
client<llm> AnthropicClient {
  provider anthropic
  options {
    model "claude-3-5-sonnet-20241022"
    api_key env.ANTHROPIC_API_KEY
    media_url_handler {
      pdf "send_url"  // Anthropic supports both URL and base64
    }
  }
}

// Vertex AI: Use URL with MIME type
client<llm> VertexClient {
  provider vertex-ai
  options {
    model "gemini-1.5-pro"
    project "your-project"
    location "us-central1"
    media_url_handler {
      pdf "send_url_add_mime_type"  // Vertex requires MIME type
    }
  }
}

// Google AI: Use conditional handling for GCS URLs
client<llm> GoogleAIClient {
  provider google-ai
  options {
    model "gemini-1.5-pro"
    api_key env.GOOGLE_API_KEY
    media_url_handler {
      pdf "send_base64_unless_google_url"  // Keep gs:// URLs, convert others
    }
  }
}

// You can configure multiple media types independently
client<llm> MultiMediaClient {
  provider openai
  options {
    model "gpt-4o"
    api_key env.OPENAI_API_KEY
    media_url_handler {
      image "send_base64"
      audio "send_url"
      pdf "send_base64"
      video "send_url"
    }
  }
}

Model Compatibility

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