Загрузить файлы
Загрузка выполняется в три этапа: запрос адреса загрузки, отправка файла, подтверждение документа. Адрес загрузки можно получить один раз; он действителен до 1 часа.
1. Запросить адрес загрузки
Заголовок раздела «1. Запросить адрес загрузки»POST /api/v1/upload/presignX-API-Key: sk_your_keyContent-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}2. Отправьте файл
Заголовок раздела «2. Отправьте файл»Отправьте PUT на upload_url, используя байты исходного файла в качестве тела сообщения, и передайте каждый заголовок из upload_headers в точном соответствии с указанным.
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous responsecurl --fail-with-body -X PUT "$UPLOAD_URL" \ -H "Content-Type: $UPLOAD_CONTENT_TYPE" \ -H "If-None-Match: *" \ --upload-file "report.docx"Не отправляйте ваш API‑ключ OmniDoc на этом этапе. Если срок действия адреса истечёт или перевод не удастся, запросите новый.
3. Подтвердите документ
Заголовок раздела «3. Подтвердите документ»POST /api/v1/upload/finalizeX-API-Key: sk_your_keyContent-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 |
403 | finalize_token принадлежит другой учётной записи |
410 | Загруженный файл не найден (передача завершена не полностью или срок действия адреса истек); запросите новый адрес |
413 | Превышено ограничение на размер файла |
415 | Неподдерживаемый формат или содержимое не соответствует расширению |
422 | Файл Office повреждён или конструктивно небезопасен |
429 | Слишком много загрузок |
503 | Сервис загрузки временно недоступен; попробуйте позже |