Перейти к содержимому

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

Загрузка выполняется в три этапа: запрос адреса загрузки, отправка файла, подтверждение документа. Адрес загрузки можно получить один раз; он действителен до 1 часа.

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-Type: application/json
{
"filename": "report.docx",
"file_size": 45678
}
ПолеТипОбязательноОписание
filenameстрока✅Имя файла; тип файла определяется сервером по расширению
file_sizeцелое число✅Точная размер в байтах, больше 0
mime_typeстрока—Необязательно; сервер его не использует

Ответ:

{
"document_id": "4q8mx2q9z1k7p6ra",
"upload_url": "https://upload.example/...",
"upload_headers": {
"Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"If-None-Match": "*"
},
"finalize_token": "short_lived_token",
"expires_in": 3600
}

Отправьте PUT на upload_url, используя байты исходного файла в качестве тела сообщения, и передайте каждый заголовок из upload_headers в точном соответствии с указанным.

Окно терминала
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous response
curl --fail-with-body -X PUT "$UPLOAD_URL" \
-H "Content-Type: $UPLOAD_CONTENT_TYPE" \
-H "If-None-Match: *" \
--upload-file "report.docx"

Не отправляйте ваш API‑ключ OmniDoc на этом этапе. Если срок действия адреса истечёт или перевод не удастся, запросите новый.

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-Type: application/json
{"finalize_token":"short_lived_token"}

В случае успеха возвращается документ:

{
"document": {
"id": "4q8mx2q9z1k7p6ra",
"basename": "report.docx",
"file_size": 45678,
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"created_at": "2026-10-01T12:00:00Z"
}
}

Только после подтверждения документ попадает в библиотеку файлов и становится доступным для использования в заданиях.

filename предназначен только для отображения; не используйте его в качестве пути или уникального идентификатора. Сервер заменяет недопустимые символы и формирует безопасное имя загрузки для слишком длинных имен.

СтатусПричина
400Недопустимое имя или размер файла, либо загруженный размер отличается от запрошенного
401Недействительные или истекшие учетные данные или finalize_token
403finalize_token принадлежит другой учётной записи
410Загруженный файл не найден (передача завершена не полностью или срок действия адреса истек); запросите новый адрес
413Превышено ограничение на размер файла
415Неподдерживаемый формат или содержимое не соответствует расширению
422Файл Office повреждён или конструктивно небезопасен
429Слишком много загрузок
503Сервис загрузки временно недоступен; попробуйте позже