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 reference to .chat() (and other chat methods) like any other content, instead of re-sending the file’s bytes on every turn. To reuse a file uploaded in an earlier session, pass the result of .get() to .chat() the same way.
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, which can be passed straight to .chat() (and other chat methods) to reference the file in a turn – e.g. to reuse a file uploaded in an earlier session: python report = chat.files.get("file_011CRabc...") chat.chat("Summarize the key findings.", report) |
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().