Video

Video 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 video data. For more details, refer to video types.

For AWS Bedrock models with video support, you can pass s3:// URIs through Video.from_url. BAML forwards the URI as an s3Location and includes the media_type you provide so Bedrock can fetch the object without uploading it through BAML first. BAML does not infer video MIME types for Bedrock requests, so always supply the correct media_type (for example, video/mp4). </Info>

Usage Examples

async def test_video_input(): # Create a Video object from a URL video = Video.from_url("https://www.youtube.com/watch?v=dQw4w9WgXcQ") res = await b.TestVideoInput(video=video)

# Create a Video object from Base64 data
video_b64 = "AAAAGGZ0eXBpc29t..."
video = Video.from_base64("video/mp4", video_b64)
res = await b.TestVideoInput(video=video)

# Pass an S3 video reference directly to an AWS Bedrock model
bedrock_video = Video.from_url(
    "s3://baml-test-bucket/example/path/video.mp4", media_type="video/mp4"
)
res = await b.TestAwsVideoDescribe(video_input=bedrock_video)

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

// Create a Video object from a URL
let res = await b.TestVideoInput(
    Video.fromUrl('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
)

// Create a Video object from Base64 data
const video_b64 = "AAAAGGZ0eXBpc29t..."
res = await b.TestVideoInput(
    Video.fromBase64('video/mp4', video_b64)
)

// Pass an S3 video reference directly to an AWS Bedrock model
const bedrockVideo = Video.fromUrl(
  's3://baml-test-bucket/example/path/video.mp4',
  'video/mp4',
)
// Pass `bedrockVideo` to any function backed by a Bedrock model with video support

// Browser-specific methods
const fileVideo = await Video.fromFile(file)
const blobVideo = await Video.fromBlob(blob, 'video/mp4')
const fetchedVideo = await Video.fromUrlToBase64('https://www.youtube.com/watch?v=dQw4w9WgXcQ')

import { useTestVideoInput } from '../baml_client/react/hooks'
import { Video } from "../baml_client/react/media"

export function TestVideoInput() {
    const { mutate } = useTestVideoInput()

    const handleClick = async () => {
        const video = await Video.fromUrl('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
        mutate(video)
    }

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

use myproject::baml_client::sync_client::B;
use myproject::baml_client::new_video_from_url;

fn test_video_input() {
    // Create a Video from a URL
    let video = new_video_from_url("https://example.com/sample.mp4", None);
    let res = B.TestVideoInput.call(&video).unwrap();
}

# Ruby implementation is in development.

API Reference

Static Methods

<ParamField path="from_url" type="(url: str, media_type: Optional[str] = None) -> Video"

Creates a Video object from a URL. Optionally specify the media type, otherwise it will be inferred from the URL. When targeting AWS Bedrock with an s3:// URI, pass the media type explicitly so the request includes the expected format. </ParamField>

<ParamField path="from_base64" type="(media_type: str, base64: str) -> Video"

Creates a Video object using Base64 encoded data along with the given MIME type. </ParamField>

Instance Methods

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

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

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

Get the URL of the video if it's stored as a URL. Raises an exception if the video is not stored as a URL. </ParamField>

<ParamField path="as_base64" type="() -> list[str]"

Get the base64 data and media type if the video is stored as base64. Returns [base64_data, media_type]. Raises an exception if the video is not stored as base64. </ParamField>

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

Convert the video 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) => Video"

Creates a Video object from a URL. Optionally specify the media type, otherwise it will be inferred from the URL. When targeting AWS Bedrock with an s3:// URI, pass the media type explicitly so the request includes the expected format. </ParamField>

<ParamField path="fromBase64" type="(mediaType: string, base64: string) => Video"

Creates a Video object using Base64 encoded data along with the given MIME type. </ParamField>

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

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

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

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

<ParamField path="fromUrlToBase64" type="(url: string) => Promise<Video>"

<Info>Only available in browser environments.</Info> Creates a Video object by fetching from a URL. Available in browser environments only. </ParamField>

Instance Methods

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

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

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

Get the URL of the video if it's stored as a URL. Throws an Error if the video is not stored as a URL. </ParamField>

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

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

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

Convert the video to a JSON representation. Returns either a URL object or a base64 object with media type. </ParamField>

Static Methods

<ParamField path="NewVideoFromUrl" type="(url string, mediaType *string) (*Video, error)"

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

<ParamField path="NewVideoFromBase64" type="(base64 string, mediaType *string) (*Video, error)"

Creates a Video object using Base64 encoded data along with the given MIME type. </ParamField>

Instance Methods

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

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

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

Get the URL of the video if it's stored as a URL. Returns an error if the video is not stored as a URL. </ParamField>

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

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

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

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

Static Methods

<ParamField path="new_video_from_url" type="(url: &str, media_type: Option<&str>) -> BamlVideo"

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

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

Creates a Video from Base64 encoded data with an optional MIME type. </ParamField>

Ruby implementation is in development.

URL Handling

Video URLs are typically passed directly to providers without conversion (default: never for all providers). This is because:

1. Video files are often too large for base64 encoding
2. Most providers that support video input can fetch URLs directly
3. Base64 encoding videos significantly increases payload size

Provider defaults:

• OpenAI: Keeps URLs as-is (send_url)
• Anthropic: Keeps URLs as-is (send_url)
• Google AI: Keeps URLs as-is (send_url)
• Vertex AI: Keeps URLs as-is (send_url)
• AWS Bedrock: Keeps URLs as-is (send_url)

For Bedrock, s3:// URLs are passed through unchanged and encoded in the request body as an s3Location, allowing Bedrock to fetch the object directly from S3 without routing bytes through BAML.

You can override this behavior using media_url_handler.video in your client configuration, but be aware of size limitations when using send_base64 mode.

Model Compatibility

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