FileManager
FileManager(provider)Manage files hosted by a chat’s provider. Accessed via chat.files.
Upload a file once with .upload(), then pass the returned ContentUploaded to .chat() (and other chat methods) like any other content, instead of re-sending the file’s bytes on every turn.
Supported for ChatOpenAI() (the Responses API), ChatAnthropic(), and ChatGoogle() (the Gemini Developer API). Every other provider – including ChatOpenAICompletions(), OpenAI-compatible third parties (ChatGroq(), ChatMistral(), ChatOllama(), etc.), ChatAzureOpenAI(), ChatBedrockAnthropic(), ChatPosit(), and Vertex-backed chats (ChatVertex(), or ChatGoogle() configured for Vertex) – raises NotImplementedError from every method here.
Notes
- Anthropic’s Files API is still in beta. chatlas automatically adds the required
anthropic-beta: files-api-2025-04-14header whenever a turn references an uploaded file. - Gemini Developer API files expire automatically after 48 hours, and the Files API isn’t available on Vertex AI at all. To reference a file already in Cloud Storage on a Vertex-backed chat, construct
ContentUploadeddirectly with ags://URI instead of calling.upload(). ChatOpenAICompletions()can reference an uploaded PDF or text document, but not an uploaded image – the Chat Completions API doesn’t support it. UseChatOpenAI()(Responses API) for uploaded images, or pass the image inline withcontent_image_file().
Methods
| Name | Description |
|---|---|
| delete | Delete a previously uploaded file from the provider. |
| delete_async | Async version of .delete(). |
| download | Download a file’s raw bytes, optionally writing them to path. |
| download_async | Async version of .download(). |
| get | Get metadata for a previously uploaded file. |
| get_async | Async version of .get(). |
| list | List files previously uploaded to the chat’s provider. |
| list_async | Async version of .list(). |
| upload | Upload a file to the chat’s provider, once, for reuse across turns. |
| upload_async | Async version of .upload(). |
delete
FileManager.delete(id)Delete a previously uploaded file from the provider.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| id | str | The provider-assigned file id (e.g., ContentUploaded.id). |
required |
delete_async
FileManager.delete_async(id)Async version of .delete().
download
FileManager.download(id, path=None)Download a file’s raw bytes, optionally writing them to path.
Whether a file is downloadable depends on how it was created, so this raises a provider error for anything .upload() produced:
- OpenAI refuses
purpose="user_data"(what.upload()uses), but allowspurpose="batch"/"batch_output"— i.e. the input and result files behindbatch_chat(). - Anthropic marks uploaded files as not downloadable.
- Google only serves bytes back for model-generated files (e.g. Veo video output).
download_async
FileManager.download_async(id, path=None)Async version of .download().
get
FileManager.get(id)Get metadata for a previously uploaded file.
Only supported for ChatOpenAI, ChatAnthropic, and ChatGoogle; other providers raise NotImplementedError.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| id | str | The provider-assigned file id (e.g., ContentUploaded.id). |
required |
Returns
| Name | Type | Description |
|---|---|---|
| FileMetadata | Metadata for the file. |
get_async
FileManager.get_async(id)Async version of .get().
list
FileManager.list()List files previously uploaded to the chat’s provider.
Only supported for ChatOpenAI, ChatAnthropic, and ChatGoogle; other providers raise NotImplementedError.
Returns
| Name | Type | Description |
|---|---|---|
| list[FileMetadata] | Metadata for each file hosted by the provider. |
list_async
FileManager.list_async()Async version of .list().
upload
FileManager.upload(file, *, mime_type=None)Upload a file to the chat’s provider, once, for reuse across turns.
Only supported for ChatOpenAI, ChatAnthropic, and ChatGoogle; other providers raise NotImplementedError.
Prefer this over the inline content_*_file() functions when the file is large or referenced across many turns, since those re-send its bytes on every request. Prefer them when you want portability: the returned reference is an id belonging to this provider, so a chat containing one can’t be replayed elsewhere.
On ChatGoogle(), this blocks until Gemini finishes processing the file: large media (video, audio, multi-GB uploads) is processed asynchronously, and the API refuses to reference a file that isn’t yet ACTIVE. That means this call can take a while for a large video, and raises if the file fails to process – but the reference you get back is always ready to use.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| file | str | os.PathLike[str] | IO[bytes] | A path to a file, or a binary file-like object, to upload. | required |
| mime_type | Optional[str] | The file’s MIME type. If not provided, it’s guessed from file. |
None |
Returns
| Name | Type | Description |
|---|---|---|
| ContentUploaded | A reference to the uploaded file that can be passed to .chat() (and other chat methods) in place of the file’s raw bytes. |
upload_async
FileManager.upload_async(file, *, mime_type=None)Async version of .upload().