Multimodal & File Uploads
Relevant source files
The following files were used as context for generating this wiki page:
The Anthropic Go SDK supports multimodal capabilities and document processing through two primary mechanisms: direct Base64 image embedding and the Beta Files API for larger document uploads. These features allow Claude to process and reason across different media types, including images and text-based documents, integrated directly into the conversational flow.
Multimodal interactions are handled via specific content block types within the Messages API, while document processing often requires a preliminary upload step to generate a file identifier that is subsequently referenced in a message.
Image Processing (Multimodal)
Image processing is achieved by embedding image data directly into a message using a Base64-encoded string. This is a synchronous operation where the image data is part of the standard Messages.New request.
Implementation Flow
To send an image, a developer must read the local file, encode it to Base64, and create an ImageBlock within a UserMessage.
The process uses the anthropic.NewImageBlockBase64 function, which requires the MIME type (e.g., "image/png") and the encoded data.
Sources: examples/multimodal/main.go:19-40
Beta Files API
The Beta Files API provides a structured way to upload, manage, and reference files (such as .txt or .pdf) that are too large for direct embedding or need to be reused across multiple requests. Accessing these features requires the inclusion of specific beta headers.
File Upload and Reference Lifecycle
The lifecycle involves uploading a file to obtain a FileID, which is then referenced using a DocumentBlock in a message request.
Key Data Structures
The SDK uses several structures to manage file metadata and upload parameters.
| Structure | Purpose | Key Fields |
|---|---|---|
FileMetadata | Represents a file on Anthropic's servers | ID, Filename, MimeType, SizeBytes, CreatedAt |
BetaFileUploadParams | Parameters for the upload request | File (io.Reader), Betas (Beta headers) |
BetaFileDocumentSourceParam | References an uploaded file in a message | FileID |
Sources: betafile.go:128-150, betafile.go:193-198, examples/file-upload/main.go:42-44
File Management Operations
The BetaFileService provides standard CRUD-like operations for managing uploaded artifacts. These operations typically require the AnthropicBetaFilesAPI2025_04_14 header.
API Endpoints and Methods
| Method | Description | Endpoint |
|---|---|---|
Upload | Uploads a new file from an io.Reader | POST /v1/files |
GetMetadata | Retrieves metadata for a specific file | GET /v1/files/{file_id} |
List | Lists all files in the workspace (paginated) | GET /v1/files |
Download | Downloads the binary content of a file | GET /v1/files/{file_id}/content |
Delete | Removes a file from the server | DELETE /v1/files/{file_id} |
Sources: betafile.go:37-113
The File Helper
The SDK provides a File helper function in field.go to wrap an io.Reader with necessary metadata (filename and content type) before passing it to the upload service.
func File(rdr io.Reader, filename string, contentType string) file {
return file{rdr, filename, contentType}
}
Sources: field.go:23-25, examples/file-upload/main.go:25
Advanced Content Blocks
When using Beta features, the message content blocks can include specialized types for document interaction and citations.
Beta Content Types
- TextBlock: Standard text, which may now include
Citationsreferencing specific document indices or character locations. - DocumentBlock: A reference to an uploaded file via its
FileID. - ThinkingBlock: Used in models that support extended reasoning before providing a final answer.
Summary
Multimodal and file upload capabilities expand the SDK's utility beyond simple text chat. Direct image embedding allows for immediate visual analysis, while the Beta Files API enables complex document processing workflows by separating the heavy upload process from the inference request. Developers must manage file IDs and ensure appropriate beta headers are included in requests to leverage these document reasoning features.