Завантажити файли
Завантаження відбувається у три етапи: запит адреси завантаження, надсилання файлу, підтвердження документа. Адресу завантаження можна отримати один раз, і вона дійсна до 1 години.
1. Запитати адресу завантаження
Section titled “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. Надішліть файл
Section titled “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. Підтвердьте документ
Section titled “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" }}Лише після підтвердження документ потрапляє до бібліотеки файлів і стає доступним для використання у завданнях.
Імена файлів
Section titled “Імена файлів”filename призначено лише для відображення; не використовуйте його як шлях або унікальний ідентифікатор. Сервер замінює недопустимі символи та генерує безпечне ім’я завантаження для імен, що занадто довгі.
Помилки
Section titled “Помилки”| Статус | Причина |
|---|---|
400 | Недійсна назва або розмір файлу, або завантажений розмір відрізняється від запитаного |
401 | Недійсні або прострочені облікові дані або finalize_token |
403 | finalize_token належить іншому обліковому запису |
410 | Завантажений файл не знайдено (передача неповна або адреса прострочена); запитайте нову адресу |
413 | Перевищено обмеження розміру файлу |
415 | Непідтримуваний формат або вміст не відповідає розширенню |
422 | Файл Office пошкоджено або має ненадійну структуру |
429 | Завеликі обсяги завантажень |
503 | Сервіс завантаження тимчасово недоступний; спробуйте пізніше |