# How to Perform File Uploads Using the Anthropic Python SDK

> Easily upload files to Anthropic's API with the Python SDK. Learn to use client.beta.files.upload() with file paths, bytes, or file-like objects and get your file ID.

- Repository: [Anthropic/anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Upload files to Anthropic's API by accessing `client.beta.files.upload()` with a file path, bytes, or file-like object, which returns a `FileMetadata` object containing the assigned file ID.**

The `anthropics/anthropic-sdk-python` repository provides a type-safe, ergonomic interface for interacting with Anthropic's API. Understanding how to perform file uploads using the Anthropic Python SDK requires familiarity with its layered architecture, which cleanly separates the HTTP client, beta resource groups, and specific endpoint implementations.

## Understanding the SDK Architecture for File Uploads

The SDK organizes file operations through a hierarchical structure that routes requests from the main client down to specialized resource classes.

### The Client Layer

The `Anthropic` class serves as the primary entry point, handling authentication via the `ANTHROPIC_API_KEY` environment variable or explicit `api_key` parameter, configuring base URLs, and managing retry logic. This class exposes the `beta` property, which lazy-loads beta-specific resources.

*Source*: [`src/anthropic/_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_client.py)

### The Beta Resource Group

The `beta` namespace isolates experimental APIs under `client.beta`. This group dynamically loads sub-resources like `files` only when accessed, preventing unnecessary initialization overhead.

*Source*: [`src/anthropic/resources/beta/__init__.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/__init__.py)

### The Files Resource

The `Files` class implements the file-related endpoints including `list`, `delete`, `download`, `retrieve_metadata`, and `upload`. The synchronous implementation resides in [`src/anthropic/resources/beta/files.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/files.py) (lines 75-89), while the asynchronous counterpart occupies lines 69-80 in the same file.

The `upload` method constructs a `multipart/form-data` request, extracts the file payload using `extract_files`, adds the required `Content-Type` header, and invokes the generic `_post` helper inherited from `SyncAPIResource` or `AsyncAPIResource`.

## How to Upload Files Using the Anthropic Python SDK

The SDK accepts multiple input types through the `FileTypes` union defined in [`src/anthropic/_types.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_types.py): `str` (file path), `bytes`, or `io.IOBase` (file-like objects).

### Synchronous File Upload

The most common approach opens a local file path and returns a `FileMetadata` object containing the file ID, size, and MIME type.

```python
from anthropic import Anthropic

client = Anthropic()  # Reads ANTHROPIC_API_KEY from environment

# Upload a local file; SDK returns metadata with generated file_id

metadata = client.beta.files.upload(file="my_image.png")

print(f"Uploaded file ID: {metadata.id}")
print(f"Size (bytes): {metadata.bytes}")
print(f"MIME type: {metadata.mime_type}")

```

### Uploading Raw Bytes

For in-memory data, pass a `bytes` object directly without writing to disk.

```python
from anthropic import Anthropic

client = Anthropic()

image_bytes = b"\x89PNG..."  # Binary content of a PNG image

metadata = client.beta.files.upload(file=image_bytes)

print(metadata.id)

```

### Asynchronous File Upload

For non-blocking I/O, use `AsyncAnthropic` with `async`/`await` syntax.

```python
import asyncio
from anthropic import AsyncAnthropic

async def main() -> None:
    client = AsyncAnthropic()
    async with client:
        metadata = await client.beta.files.upload(file="document.pdf")
        print(f"File ID: {metadata.id}")

asyncio.run(main())

```

### Using File-Like Objects

Any object implementing the `io.IOBase` protocol works, including opened file handles.

```python
from anthropic import Anthropic

client = Anthropic()

with open("report.txt", "rb") as f:
    metadata = client.beta.files.upload(file=f)
    print(metadata.id)

```

## Understanding the Upload Implementation

Under the hood, the `upload` method in [`src/anthropic/resources/beta/files.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/files.py) performs several critical operations:

1. **Header Construction**: Injects the required `anthropic-beta: files-api-2025-04-14` header to access the beta files API
2. **Body Preparation**: Creates a deep copy of the request body containing the file reference
3. **File Extraction**: Uses `extract_files` to parse the `FileTypes` input and prepare multipart boundaries
4. **Content-Type Override**: Sets `Content-Type: multipart/form-data` to ensure proper MIME handling
5. **HTTP POST**: Dispatches to `/v1/files?beta=true` via the inherited `_post` method and casts the response to `FileMetadata`

This architecture ensures type safety while supporting multiple input formats through the `FileTypes` union.

## Summary

- Access file uploads through `client.beta.files.upload()` using the `Anthropic` or `AsyncAnthropic` client
- The SDK accepts `str` paths, `bytes` objects, or `io.IOBase` file-like objects via the `FileTypes` union
- Uploads return a `FileMetadata` object containing the file ID, size, and MIME type
- The implementation resides in [`src/anthropic/resources/beta/files.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/files.py) and requires the `files-api-2025-04-14` beta header
- Both synchronous and asynchronous patterns are fully supported through the unified resource interface

## Frequently Asked Questions

### What file types does the Anthropic Python SDK support for uploads?

The SDK accepts any file type through the `FileTypes` union defined in [`src/anthropic/_types.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_types.py), which includes `str` (file system paths), `bytes` (in-memory binary data), and `io.IOBase` (file-like objects such as opened file handles or BytesIO streams). The API itself may impose restrictions on specific MIME types or file sizes depending on the endpoint configuration.

### How do I handle asynchronous file uploads in the Anthropic SDK?

Use the `AsyncAnthropic` client class instead of the standard `Anthropic` client. The asynchronous files resource is available at `client.beta.files` and supports `await` syntax for non-blocking uploads. The implementation in [`src/anthropic/resources/beta/files.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/files.py) (lines 69-80) handles the async HTTP POST operation while maintaining the same `FileTypes` input flexibility as the synchronous version.

### Where is the file upload implementation located in the source code?

The core upload logic resides in [`src/anthropic/resources/beta/files.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/files.py) within the `Files` class. The synchronous `upload` method spans lines 75-89, while the asynchronous variant occupies lines 69-80. This method constructs the multipart request body, extracts file data using `extract_files`, sets the required `anthropic-beta: files-api-2025-04-14` header, and dispatches the POST request to `/v1/files?beta=true` via the inherited `_post` helper from the base resource classes.