Загрузить файл

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

• multipart/form-data: загрузка локального файла.
• application/json: загрузка base64-содержимого.

Один запрос может загрузить только один файл; для загрузки нескольких файлов выполните несколько запросов. При успешной загрузке API возвращает объект файла.

POST https://api.odirouter.ai/v1/files

Ограничения загрузки

Ограничение	Значение	Описание
Размер одного файла	40MB	Если файл или декодированное base64-содержимое превышает лимит, API вернет 413 file_too_large
Срок хранения файла	7 дней	После истечения срока файл нельзя получить или скачать
Срок одного подписанного URL	1 час	Если URL истек, но файл еще доступен в течение 7 дней, можно снова запросить информацию о файле и получить новый URL; срок подписи не превысит оставшийся срок файла
Частота запросов	10 запросов/минуту	Стандартное ограничение частоты запросов для POST /v1/files

Аутентификация

Используйте Bearer-аутентификацию с API Key:

Authorization: Bearer YOUR_API_KEY

Файлы принадлежат пользователю, связанному с текущим API Key. Платформа записывает API Key, которым создан файл, для аудита и статистики использования.

curl --location "https://api.odirouter.ai/v1/files" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --form "file=@./reference.png"

curl --location "https://api.odirouter.ai/v1/files" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mime_type": "image/png",
    "filename": "reference.png"
  }'

Тело multipart/form-data

file file обязательно

Один файл для загрузки

При загрузке локального файла платформа использует исходное имя файла; например file=@./reference.png будет записан как reference.png

Тело application/json

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

Содержимое файла в base64

Поддерживается обычная base64-строка или data URL

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

MIME-тип файла, например image/png

Если data передан как data URL и MIME в data URL не совпадает с mime_type, API вернет 400 invalid_request

filename string

Имя файла, например reference.png

Если не передано, платформа сгенерирует имя автоматически

Параметры ответа

{
  "id": "file_456",
  "object": "file",
  "filename": "reference.png",
  "bytes": 345678,
  "mime_type": "image/png",
  "file_type": "image",
  "source": "upload",
  "dimensions": {
    "width": 1024,
    "height": 768
  },
  "storage_policy": "temporary",
  "created_at": 1784256000,
  "expires_at": 1784860800,
  "url": "https://private.cdn.odirouter.ai/uploads/xxx.png?Expires=..."
}

{
  "error": {
    "message": "Invalid request parameters.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}

{
  "error": {
    "message": "File exceeds the size limit.",
    "type": "invalid_request_error",
    "param": "file",
    "code": "file_too_large"
  }
}

{
  "error": {
    "message": "user request rate limit exceeded (request id: 202607211234567890)",
    "type": "api_error",
    "code": "rate_limit_exceeded"
  }
}

{
  "error": {
    "message": "Object storage service unavailable.",
    "type": "api_error",
    "code": "storage_unavailable"
  }
}

Поле	Тип	Описание
id	string	ID файла в формате file_{id}
object	string	Всегда file
filename	string	Исходное имя файла; если имя не передано, его генерирует платформа
bytes	integer	Размер файла в байтах
mime_type	string	MIME-тип файла
file_type	string	Тип файла. Возможные значения в ответе: image, audio, video, document, text
source	string	Источник файла. Для загрузки через этот API возвращается upload
dimensions	object | null	Размеры файла. Для JPEG, PNG и GIF возвращается ширина и высота; для остальных файлов или неподдерживаемых форматов изображений возвращается null
dimensions.width	integer	Ширина в пикселях; возвращается только если dimensions не равен null
dimensions.height	integer	Высота в пикселях; возвращается только если dimensions не равен null
storage_policy	string	Политика хранения. Сейчас всегда temporary
created_at	integer	Время создания, Unix timestamp в секундах
expires_at	integer	Время истечения, Unix timestamp в секундах. В текущей версии у всех файлов есть конкретное время истечения
url	string	Единственный внешний адрес для доступа к файлу. Это текущий краткоживущий подписанный URL со сроком действия и параметрами подписи; после истечения срока нужно снова запросить информацию о файле, чтобы получить новый адрес

MIME и типы файлов

MIME	file_type	dimensions
image/jpeg	image	Возвращает ширину и высоту
image/png	image	Возвращает ширину и высоту
image/gif	image	Возвращает ширину и высоту
image/webp	image	null
audio/mpeg	audio	null
audio/wav	audio	null
audio/mp4	audio	null
audio/webm	audio	null
video/mp4	video	null
video/quicktime	video	null
video/webm	video	null
application/pdf	document	null
text/plain	text	null
text/csv	text	null
application/json	text	null

Ошибки

HTTP статус	code	Описание
400	invalid_request	Ошибка в параметрах запроса
400	file_required	В запросе загрузки отсутствует поле file
400	invalid_base64	base64-содержимое пустое или не может быть декодировано
400	unsupported_file_type	Тип файла не поддерживается
413	file_too_large	Файл превышает лимит размера
429	rate_limit_exceeded	Превышен лимит частоты загрузки
500	storage_unavailable	Сервис объектного хранилища недоступен