Files API

Files API позволяет загружать файлы и управлять ими для использования с Claude API без повторной загрузки содержимого при каждом запросе. Это особенно полезно при использовании инструмента выполнения кода для предоставления входных данных (например, наборов данных и документов) и последующего скачивания результатов (например, диаграмм). Вы также можете использовать Files API, чтобы избежать постоянной повторной загрузки часто используемых документов и изображений в нескольких вызовах API. В дополнение к этому руководству вы можете изучить справочник по API напрямую.

Поддерживаемые модели

Ссылка на file_id в запросе Messages поддерживается во всех моделях, которые поддерживают данный тип файла. Изображения поддерживаются во всех текущих моделях Claude. Для PDF-файлов и других типов файлов с инструментом выполнения кода см. поддержку моделей на соответствующих страницах.

Files API доступен в Claude API, Claude Platform на AWS и Microsoft Foundry. В настоящее время он недоступен в Amazon Bedrock или Vertex AI.

Как работает Files API

Files API предоставляет простой подход «создать один раз, использовать многократно» для работы с файлами:

• Загружайте файлы в защищённое хранилище Anthropic и получайте уникальный file_id
• Скачивайте файлы, созданные навыками или инструментом выполнения кода
• Ссылайтесь на файлы в запросах Messages, используя file_id вместо повторной загрузки содержимого
• Управляйте своими файлами с помощью операций получения списка, извлечения и удаления

Как использовать Files API

Загрузка файла

Загрузите файл, на который можно будет ссылаться в будущих вызовах API:

uploaded = client.beta.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)

Ответ на загрузку файла будет содержать:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false
}

Использование файла в сообщениях

После загрузки ссылайтесь на файл, используя его file_id:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)

Типы файлов и блоки содержимого

Files API поддерживает различные типы файлов, которые соответствуют различным типам блоков содержимого:

Работа с другими форматами файлов

Для типов файлов, которые не поддерживаются как блоки document (.csv, .txt, .md, .docx, .xlsx), преобразуйте файлы в обычный текст и включите содержимое непосредственно в ваше сообщение:

import pandas as pd
# ...
# Пример: чтение CSV-файла
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# Отправить как обычный текст в сообщении
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
                }
            ],
        }
    ],
)

print(response.content[0].text)

Блоки документов

Для 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"
  }
}

Управление файлами

Получение списка файлов

Получите список загруженных вами файлов:

client = anthropic.Anthropic()
files = client.beta.files.list()

Получение метаданных файла

Получите информацию о конкретном файле:

file = client.beta.files.retrieve_metadata(file_id)

Удаление файла

Удалите файл из вашего рабочего пространства:

result = client.beta.files.delete(file_id)

Скачивание файла

Скачивайте файлы, созданные навыками или инструментом выполнения кода:

file_content = client.beta.files.download(file_id)

# Save to file
file_content.write_to_file("downloaded_file.txt")

Хранение файлов и ограничения

Ограничения хранилища

• Максимальный размер файла: 500 МБ на файл
• Общий объём хранилища: 500 ГБ на организацию

Жизненный цикл файла

• Файлы привязаны к рабочему пространству ключа API. Другие ключи API могут использовать файлы, созданные любым другим ключом API, связанным с тем же рабочим пространством
• Файлы сохраняются до тех пор, пока вы их не удалите
• Удалённые файлы не могут быть восстановлены
• Файлы становятся недоступными через API вскоре после удаления, но они могут сохраняться в активных вызовах API Messages и связанных с ними операциях использования инструментов
• Файлы, которые удаляют пользователи, будут удалены в соответствии с политикой хранения данных Anthropic.

Хранение данных

Файлы, загруженные через Files API, хранятся до тех пор, пока не будут явно удалены с помощью конечной точки DELETE /v1/files/{file_id}. Файлы хранятся для повторного использования в нескольких запросах API.

Информацию о соответствии требованиям ZDR для всех функций см. в разделе API и хранение данных.

Обработка ошибок

Распространённые ошибки при использовании Files API включают:

• Файл не найден (404): Указанный file_id не существует, или у вас нет к нему доступа
• Недопустимый тип файла (400): Тип файла не соответствует типу блока содержимого (например, использование файла изображения в блоке документа)
• Превышен размер контекстного окна (400): Файл больше, чем размер контекстного окна (например, использование текстового файла размером 500 МБ в запросе /v1/messages)
• Недопустимое имя файла (400): Имя файла не соответствует требованиям к длине (1–255 символов) или содержит запрещённые символы (<, >, :, ", |, ?, *, \, / или символы Unicode 0–31)
• Файл слишком большой (413): Файл превышает ограничение в 500 МБ
• Превышен лимит хранилища (403): Ваша организация достигла лимита хранилища в 500 ГБ

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

Использование и тарификация

Операции File API бесплатны:

• Загрузка файлов
• Скачивание файлов
• Получение списка файлов
• Получение метаданных файла
• Удаление файлов

Содержимое файлов, используемое в запросах Messages, тарифицируется как входные токены. Вы можете скачивать только файлы, созданные навыками или инструментом выполнения кода.

Ограничения скорости

В период бета-тестирования:

• Вызовы API, связанные с файлами, ограничены примерно 100 запросами в минуту
• Свяжитесь с нами, если вам нужны более высокие лимиты для вашего варианта использования