Files API
Загружайте файлы один раз, ссылайтесь на них по file_id в запросах Messages и скачивайте результаты, созданные навыками или инструментом выполнения кода.
Использование зависит от продукта
file_id в блоке document, image или container_upload.file_id в событии user.message.Files API позволяет загружать файлы и управлять ими для использования с Claude API без повторной загрузки содержимого при каждом запросе. Это особенно полезно при использовании инструмента выполнения кода для предоставления входных данных (например, наборов данных и документов) и последующего скачивания результатов (например, диаграмм). В дополнение к этому руководству вы можете изучить справочник API напрямуюДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..
Поддержка типов файлов
Ссылка на file_id в запросе Messages поддерживается на всех моделях, которые поддерживают данный тип файла. Изображения поддерживаются всеми текущими моделями Claude. Для PDF и других типов файлов с инструментом выполнения кода см. соответствующие страницы, чтобы узнать о поддержке моделей.
Как работает Files API
Files API предоставляет подход «создать один раз — использовать многократно» для работы с файлами:
- Загружайте файлы в защищённое хранилище Anthropic и получайте уникальный
file_id - Скачивайте файлы, созданные навыками или инструментом выполнения кода
- Ссылайтесь на файлы в запросах MessagesДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape., используя
file_idвместо повторной загрузки содержимого - Управляйте своими файлами с помощью операций получения списка, извлечения и удаления
Файлы не привязаны к конечному пользователю, беседе или сеансу. Любой ключ API с доступом к рабочему пространству может получить доступ к любым файлам, загруженным в это рабочее пространство. Каждая сервисная учётная запись и каждый пользователь, чья роль в организации разрешает доступ к API, могут использовать рабочее пространство по умолчанию (Default Workspace) в дополнение к любому рабочему пространству, в которое вы их добавите, поэтому храните файлы, которые должны оставаться изолированными, в отдельном рабочем пространстве и обращайтесь к ним только с помощью ключей, ограниченных этим рабочим пространством. Никогда не принимайте значения file_id от конечных пользователей или других ненадёжных источников: идентификатор файла, предоставленный пользователем, позволил бы одному пользователю вашего приложения прочитать содержимое, загруженное другим пользователем. Рассматривайте идентификаторы файлов как серверные ссылки и храните сопоставление между вашими пользователями и их файлами в своём приложении.
Если вы создаёте мультитенантное приложение на основе Files API, создайте отдельное рабочее пространство для каждого арендатора (tenant). Рабочее пространство является границей изоляции для файлов, поэтому отдельное рабочее пространство для каждого арендатора обеспечивает жёсткую изоляцию данных этого арендатора от всех остальных. Каждая организация может иметь до 100 рабочих пространств; если вам нужно больше, свяжитесь с вашей командой по работе с клиентами.
Как использовать Files API
Загрузка файла
Загрузите файл, чтобы ссылаться на него в будущих вызовах API:
uploaded = client.files.upload(
file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)Ответ на загрузку файла включает:
{
"id": "file_011CNha8iCJcU1wXNR6q4V8w",
"type": "file",
"filename": "document.pdf",
"mime_type": "application/pdf",
"size_bytes": 1024000,
"created_at": "2025-01-01T00:00:00Z",
"downloadable": false,
"expires_at": null
}downloadableДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. имеет значение false для загруженных вами файлов. Скачать можно только файлы, созданные навыками или инструментом выполнения кода. См. раздел Скачивание файла.
Справочник API описывает каждое поле объекта файла.
Использование файла в сообщениях
После загрузки ссылайтесь на файл, передавая id из ответа на загрузку в качестве file_id:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Please summarize this document for me."},
{
"type": "document",
"source": {
"type": "file",
"file_id": file_id,
},
},
],
}
],
)
print(response)Типы файлов и блоки содержимого
Files API поддерживает различные типы файлов, которые соответствуют различным типам блоков содержимого:
| Тип файла | MIME-тип | Тип блока содержимого | Сценарий использования |
|---|---|---|---|
application/pdf | document | Анализ текста, обработка документов | |
| Простой текст | text/plain | document | Анализ текста, обработка |
| Изображения | image/jpeg, image/png, image/gif, image/webp | image | Анализ изображений, визуальные задачи |
| Наборы данных, прочее (см. Загрузка и анализ собственных файлов) | Различается | container_upload | Анализ данных, визуализация |
Блоки документов
Для PDF и текстовых файлов используйте блок содержимого document:
{
"type": "document",
"source": {
"type": "file",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
},
"title": "Document Title", // Optional
"context": "Context about the document", // Optional
"citations": { "enabled": true } // Optional, enables citations
}Блоки изображений
Для изображений используйте блок содержимого image:
{
"type": "image",
"source": {
"type": "file",
"file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
}
}Блоки загрузки в контейнер
Чтобы отправить файл инструменту выполнения кода, используйте блок контента container_upload:
{
"type": "container_upload",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}Работа с другими форматами файлов
Для типов файлов, которые не поддерживаются блоком document (например, .docx и .xlsx), преобразуйте файлы в обычный текст и включите содержимое непосредственно в сообщение. Файлы, которые уже являются обычным текстом, например файлы .csv и .md, можно либо прочитать таким образом, либо загрузить через Files API с явным указанием типа содержимого text/plain. Чтобы анализировать наборы данных, а не читать их как текст, загрузите их для инструмента выполнения кода с помощью блока container_upload (см. Загрузка и анализ собственных файлов).
Следующие примеры читают текстовый файл и отправляют его содержимое как простой текст:
client = anthropic.Anthropic()
# Прочитать текстовый файл
with open("document.txt") as f:
text_content = f.read()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": f"""Here's the document content:
{text_content}
Please summarize this document.""",
}
],
}
],
)
for block in response.content:
if block.type == "text":
print(block.text)Управление файлами
Получение списка файлов
Получите список загруженных вами файлов. Эндпоинт использует пагинацию: каждый запрос возвращает до limitДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. файлов (по умолчанию 20, максимум 1 000), а курсор next_pageДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. из ответа позволяет получить следующую страницу, если передать его обратно в параметре pageДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.. Файлы упорядочены от новых к старым. См. справочник API «Список файлов»Доступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.. SDK возвращает первую страницу и предоставляет вспомогательные средства автоматической пагинации.
client = anthropic.Anthropic()
files = client.files.list()
print(files)Чтобы проверить известный набор файлов одним запросом вместо постраничного перебора, передайте до 100 идентификаторов файлов в виде параметров запроса ids[]. Запрос с ids[] отличается от постраничного получения списка в трёх отношениях:
ids[]нельзя комбинировать сpageилиlimit.- Ответ всегда состоит из одной страницы (
next_pageравенnull). - Если идентификатор не соответствует файлу в вашем рабочем пространстве, API исключает этот идентификатор из
data, не возвращая ошибку. Чтобы найти идентификаторы, которые API исключил, сравните возвращённые идентификаторы с запрошенными.
Получение метаданных файла
Получите информацию о конкретном файле:
file = client.files.retrieve_metadata(file_id)
print(file)Удаление файла
Удалите файл из своего рабочего пространства:
client.files.delete(file_id)Скачивание файла
Скачивайте файлы, которые создали навыки или инструмент выполнения кода. Файлы, которые вы загружаете, скачать нельзя. file_id сгенерированного файла появляется в блоке содержимого bash_code_execution_tool_result ответа Messages, который создал этот файл. Используйте этот file_id в запросе на скачивание:
file_content = client.files.download(file_id)
file_content.write_to_file("downloaded_file.txt")В Claude API поддерживаемые файлы изображений, видео и аудио, которые Claude создаёт с помощью инструмента выполнения кода, включая файлы, созданные навыками, при скачивании содержат подписанные учётные данные содержимого C2PA (Content Credentials). О том, что содержат эти учётные данные и как их проверить, см. в разделе Content Credentials в сгенерированных файлах.
Хранение файлов и ограничения
Ограничения хранилища
- Максимальный размер файла: 500 МБ на каждый файл
- Общий объём хранилища: 1 ТБ на каждую организацию
Жизненный цикл файла
- Файлы привязаны к рабочему пространству, в которое они были загружены. Любой запрос в том же рабочем пространстве может ссылаться на них; никогда не принимайте идентификаторы файлов из ненадёжных источников (см. предупреждение о доступе в рабочем пространстве).
- Файлы нельзя изменить или переименовать после загрузки. Чтобы изменить содержимое файла, загрузите новый файл и удалите старый.
- Файлы хранятся до тех пор, пока вы не удалите их с помощью эндпоинта
DELETE /v1/files/{file_id}или пока не наступит ихexpires_at. - Удалённые файлы невозможно восстановить.
- Файлы становятся недоступны через API вскоре после удаления, но могут сохраняться в активных вызовах Messages API и связанных с ними случаях использования инструментов.
- Файлы, удалённые пользователями, будут удалены в соответствии с политикой хранения данных Anthropic.
Истечение срока действия файла
Чтобы срок действия файла истекал автоматически, добавьте поле формы expires_in_secondsДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. при его загрузке. Значение — целое число секунд от 3 600 (1 час) до 7 776 000 (90 дней). Полученная временная метка expires_atДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. (RFC 3339) присутствует в каждом ответе с файлом и имеет значение null для файлов, загруженных без срока действия. Срок действия задаётся один раз при загрузке и не может быть изменён.
Когда файл достигает своего expires_at:
- Скачивание его содержимого (
GET /v1/files/{file_id}/content) возвращает ошибку 404. - Запрос Messages, ссылающийся на этот файл, завершается ошибкой до начала инференса.
- Его метаданные (
GET /v1/files/{file_id}) остаются доступными для чтения в течение до 30 дней, при этомexpires_atуказывает на прошедшее время. - В течение этого периода файл продолжает отображаться в ответах со списком файлов; чтобы отфильтровать файлы с истёкшим сроком действия, сравнивайте
expires_atс текущим временем.
Удаление файла с истёкшим сроком действия с помощью DELETE /v1/files/{file_id} немедленно удаляет его метаданные, не дожидаясь окончания 30-дневного периода.
Журнал аудита
Если в вашей организации включён Compliance API, его Activity Feed (лента активности) записывает операции Files API, выполненные с помощью ключа API Claude или из Claude Console: каждая загрузка (POST /v1/files), скачивание содержимого (GET /v1/files/{file_id}/content) и удаление (DELETE /v1/files/{file_id}) отображаются как активность platform_file_uploaded, platform_file_content_downloaded или platform_file_deleted. Получение списка файлов и извлечение метаданных файлов не записываются. Операции, выполненные при выключенном Compliance API, не записываются и не могут быть восстановлены позже, поэтому настройте Compliance API, прежде чем полагаться на этот журнал аудита. На Claude Platform on AWS вместо этого проводите аудит операций с файлами с помощью событий данных AWS CloudTrail.
Миграция с files-api-2025-04-14
Files API вышел из бета-версии и не требует бета-заголовка. Миграция с files-api-2025-04-14 необязательна: запросы, которые его отправляют, продолжают работать и продолжают возвращать формы ответов бета-версии, поэтому существующая интеграция продолжает работать, пока вы её не измените. Удаление заголовка переключает эти запросы на формы, описанные на этой странице:
С files-api-2025-04-14 | Без заголовка | |
|---|---|---|
| Ответ со списком | { data, has_more, first_id, last_id } | { data, next_page }; передайте next_page обратно в качестве параметра запроса page |
| Курсоры списка | before_id, after_id | page или до 100 ids[] (before_id и after_id возвращают ошибку 400) |
expires_at в объектах файлов | Не возвращается | Всегда присутствует; null, если у файла нет срока действия |
Content-Type в части с загружаемым файлом | Обязателен | Необязателен; при отсутствии тип определяется автоматически |
Для миграции:
- Удалите бета-заголовок. Уберите
anthropic-beta: files-api-2025-04-14из своих запросов. При использовании SDK вызывайтеclient.filesвместоclient.beta.files; сохранениеclient.beta.filesработает только в выпусках SDK, которые больше не отправляют этот заголовок. Более ранние выпуски отправляют его изclient.beta.files, даже если вы не передаёте имена бета-функций. - Обновите пагинацию. Замените циклы с
after_id/before_idна курсорpage/next_pageили используйте вспомогательные средства автоматической пагинации SDK, показанные в разделе Управление файлами. - Читайте
expires_at. Поле появляется только без заголовка;nullозначает, что у файла нет срока действия (см. Истечение срока действия файла).
Пространство имён beta в SDK
SDK предоставляет Files API в двух пространствах имён. На этой странице используется стабильное пространство имён, а функции Files, находящиеся в бета-версии, используют бета-пространство имён.
Начиная с выпуска вашего SDK, указанного в следующей таблице, бета-пространство имён отличается от такового в более ранних выпусках в двух отношениях:
- Больше не отправляет
files-api-2025-04-14. - Возвращает те же форматы, что и стабильное пространство имён, но с именами типов с префиксом
Beta.
В таблице также приведены имена пространств имён каждого SDK и то, где бета-пространство имён принимает значения anthropic-beta:
| SDK | Стабильное пространство имён | Бета-пространство имён | Бета-пространство имён изменено в выпуске | Куда передаются значения anthropic-beta |
|---|---|---|---|---|
| Python | client.files | client.beta.files | 1.2.0 | betas |
| TypeScript | client.files | client.beta.files | 0.122.0 | betas |
| C# | client.Files | client.Beta.Files | 12.44.0 | Betas |
| Go | client.Files | client.Beta.Files | 1.68.0 | Betas |
| Java | client.files() | client.beta().files() | 2.59.0 | .addBeta() |
| PHP | $client->files | $client->beta->files (классы в Anthropic\Beta) | 0.45.0 | betas |
| Ruby | client.files | client.beta.files | 1.67.0 | betas |
Для функции Files, находящейся в бета-версии, используйте бета-пространство имён и передавайте значение anthropic-beta этой функции, как показано в таблице. Например, с бета-заголовком Managed Agents scope_id ограничивает список файлов файлами одного сеанса. Чтобы использовать scope_id, см. Получение списка и скачивание файлов сессии.
В выпусках, предшествующих выпуску вашего SDK в таблице, типы бета-пространства имён соответствуют форматам, которые возвращает files-api-2025-04-14. Если вы зависите от этих типов, оставайтесь на таком выпуске до завершения миграции с них.
Запросы, содержащие anthropic-beta: managed-agents-2026-04-01 без files-api-2025-04-14, получают формы, описанные на этой странице, с одним послаблением для совместимости в GET /v1/files: before_id и after_id по-прежнему принимаются (не комбинируются с page или ids[]), а ответ со списком включает has_more, first_id и last_id наряду с next_page. Более поздние бета-версии Managed Agents получают обычную форму.
Обработка ошибок
Распространённые ошибки при использовании Files API включают:
- Файл не найден (404): указанный
file_idне существует, или у вас нет к нему доступа. - Недопустимый тип файла (400): тип файла не соответствует типу блока контента (например, файл изображения используется в блоке документа).
- Файл нельзя скачать (400): загруженные вами файлы имеют
"downloadable": falseи не могут быть скачаны. Скачать можно только файлы, созданные навыками или инструментом выполнения кода. - Превышен размер контекстного окна (400): файл больше размера «context window» (контекстного окна) (например, при использовании текстового файла размером 500 МБ в запросе
/v1/messages). - Недопустимое имя файла (400): имя файла не соответствует требованиям к длине (1–255 символов) или содержит запрещённые символы (
<,>,:,",|,?,*,\,/или символы Unicode 0–31). - Файл слишком большой (413): файл превышает ограничение в 500 МБ.
- Превышено ограничение хранилища (400): ваша организация достигла ограничения хранилища в 1 ТБ.
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
},
"request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}Использование и тарификация
Операции Files API бесплатны:
- Загрузка файлов
- Скачивание файлов
- Получение списка файлов
- Получение метаданных файлов
- Удаление файлов
Содержимое файлов, используемое в запросах Messages, тарифицируется как входные токены.
Ограничения скорости
Вызовы API, связанные с файлами, ограничены приблизительно 500 запросами в минуту. Чтобы запросить более высокое ограничение, свяжитесь с отделом продаж.
Следующие шаги
Обрабатывайте PDF с помощью Claude. Извлекайте текст, анализируйте диаграммы и понимайте визуальное содержимое ваших документов.
Запускайте код на Python и Bash в изолированном контейнере, чтобы анализировать данные, создавать файлы и итеративно совершенствовать решения.
Обрабатывайте и анализируйте визуальные входные данные и генерируйте текст и код из изображений.
Доступность
Claude API
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents
- Модели
- Все модели
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Модели
- Все модели
Обработка данных
Обзор обработки данныхПрименимые конечные точки
/v1/files
Файлы хранятся, пока их явно не удалят или пока не истечёт заданный для них срок хранения. Подробнее
Эта страница была полезной?