Перейти к основному содержанию
POST
Загрузить файл
Загружает файл в ваше хранилище и возвращает публичную ссылку на него. Ссылку можно передать в image_url или file текстового запроса, а также во входные параметры медиа-задачи. Тело запроса — только multipart/form-data: отправка сырых байт или JSON с base64 не поддерживается.

Пример

Ссылку из ответа можно сразу использовать в чате:
cURL

Поля формы

Неизвестные поля формы игнорируются.

Ответ

201 Created:

Ограничения

  • Максимальный размер — 100 МБ. Превышение даёт 400 invalid_request.
  • Типы text/*, image/*, audio/*, video/* и application/pdf обрабатываются штатно.
  • Остальные типы — офисные документы, архивы, произвольный бинарный формат — не отклоняются. Метка типа отбрасывается, а тип определяется по расширению файла.
  • Единственная жёсткая проверка формата: устаревший .ppt отклоняется с 400 invalid_request.
Изображение может быть перекодировано в PNG без потерь, если получившийся файл меньше исходного. Длинная сторона при этом ограничивается 2000 пикселями. Поэтому size в ответе может оказаться меньше размера загруженного файла.

Ссылки на файл

url — обычная публичная ссылка на основной (или производный) файл. Она не подписана и не имеет срока действия: отдавать её можно кому угодно.
url — не ссылка с подписью. Если вам нужна приватная ссылка с ограничением по времени, хранилище такого не выдаёт — загрузите файл по своей схеме подписи.

Квота

Квота хранилища — на пользователя, а не на ключ. Когда она исчерпана, загрузка возвращает 413 payload_too_large.
Эндпоинта, который отдаёт текущую квоту или занятый объём, на /api/v1 нет. Лимит можно узнать только по факту отказа.

Ошибки

Хранилище использует третий формат ошибки — свой, отличный и от OpenAI, и от медиа-конверта:
Здесь нет полей param и code верхнего уровня, которые есть у OpenAI-формата. Клиент, разбирающий error.code, на этом эндпоинте получит null. Полный разбор — на странице Ошибки.

Что дальше

Список файлов

Что уже лежит в хранилище

Метаданные файла

Один файл по идентификатору

Запрос чату

Как передать ссылку в модель

Ошибки

Полная таблица кодов

Авторизации

Authorization
string
header
обязательно

API-ключ в формате sk-.... Альтернативно — заголовок X-Api-Key: sk-... (совместимо с Anthropic SDK).

Тело

multipart/form-data
file
file
обязательно

Файл. Обязателен.

asset_type
enum<string>
по умолчанию:chat_upload

Тип файла. Неизвестное значение заменяется на chat_upload.

Доступные опции:
chat_upload,
reference_image,
voice_message
session_id
string

Идентификатор сессии для привязки файла.

message_id
string

Идентификатор сообщения для привязки файла.

Ответ

Файл загружен.

asset_id
string
обязательно

Идентификатор файла в хранилище.

url
string
обязательно

Публичная ссылка на файл.

filename
string
size
integer

Размер сохранённого файла в байтах.

asset_type
string
mime_type
string