Завантаження файлів через API Token

Завантаження через API Token призначені для скриптів, автоматизованих задач і сторонніх програм. Відкривати вебінтерфейс не потрібно. Якщо передати URL сайту, token, шлях до локального файлу та реальний канал завантаження, файл можна завантажити в ImgHost, а відповідь міститиме URL файла.

Перед початком

Відкрийте адмін-панель і перейдіть до:

System Settings -> Security Settings -> API Token

Під час створення або редагування API Token переконайтеся, що він має дозвіл на завантаження та використовує реальний канал завантаження за замовчуванням. Завантаження через API Token не використовують вхід розумної маршрутизації, і скрипти також мають передавати реальний канал.

Завантаження скриптів для завантаження

Пакет документації надає два скрипти Node.js:

Скрипт	Призначення
скрипт завантаження одним запитом	Один раз викликає /upload. Корисно для невеликих файлів і перевірки підключення.
скрипт частинного завантаження	Використовує розбиття через API Token, пряме завантаження або сесії завантаження платформи. Рекомендовано для великих файлів.

Потрібен Node.js 18 або новіший.

Перелік доступних каналів

Обидва скрипти можуть показати канали завантаження, доступні поточному API Token:

node imghost-token-single-upload.mjs --base-url "https://your-domain" --token "your API Token" --list-channels
node imghost-token-chunk-upload.mjs --base-url "https://your-domain" --token "your API Token" --list-channels

Під час виведення каналів --file і --channel не потрібні. Відповідь містить канал завантаження за замовчуванням, key каналів завантаження, назви дочірніх каналів і стан балансування навантаження. Секрети, токени оновлення та інші чутливі значення конфігурації не повертаються.

Вибір режиму завантаження

Режим	Найкраще для	Опис
Завантаження одним запитом	Невеликі файли, прості скрипти, перевірки підключення	Надсилає весь файл у /upload одним запитом.
Частинне завантаження	Великі файли або файли, які можуть перевищити тайм-аут	Скрипт вибирає потік частинного, прямого або сесійного завантаження відповідно до каналу.

Для більших файлів спочатку використовуйте скрипт частинного завантаження. Завантаження одним запитом обмежені розміром запиту Cloudflare, пам'яттю Worker і власними обмеженнями кожної платформи.

Завантаження одним запитом

Скрипт одного запиту надсилає один запит до /upload.

node imghost-token-single-upload.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --file "D:\test\image.png" `
  --channel s3 `
  --folder "photos/2026"

Token також можна помістити в змінну середовища:

$env:IMGHOST_API_TOKEN="your API Token"
node imghost-token-single-upload.mjs --base-url "https://your-domain" --file "D:\test\image.png" --channel s3

Параметри завантаження одним запитом

Параметр	Обов'язково	Опис
--base-url <url>	Так	URL сайту ImgHost, наприклад https://image.ai6.me.
--token <token>	Так	API Token. Також можна використати змінну середовища IMGHOST_API_TOKEN.
--file <path>	Так	Шлях до локального файлу.
--channel <key>	Так	Канал завантаження.
--folder <path>	Ні	Папка завантаження, наприклад photos/2026 або /user/.
--name-type <type>	Ні	Режим іменування, зіставлений із серверним uploadNameType. Типово default.
--channel-name <name>	Ні	Вибирає дочірній канал або акаунт. Якщо пропущено, вирішує серверна конфігурація каналу.
--retries <n>	Ні	Кількість повторів для тимчасових помилок. Типово 3.
--timeout-ms <n>	Ні	Тайм-аут запиту. Типово 180000.
--output <pretty|json>	Ні	Формат виводу. Типово pretty.
--save-response <path>	Ні	Зберегти фінальну JSON-відповідь у файл.
--list-channels	Ні	Показати канали, доступні поточному token, і завершити роботу.

Канали для завантаження одним запитом

Key каналу	Канал
telegram / tg	Telegram
discord / dc	Discord
cfr2 / r2	Cloudflare R2
s3	S3
webdav / wd	Канал зберігання WebDAV
github / gh	GitHub Releases
gitlab / gl	GitLab Packages
huggingface / hf	Hugging Face
onedrive / od	OneDrive
googledrive / google / gd	Google Drive
dropbox / db	Dropbox
yandex / yx	Yandex Disk
pcloud / pd	pCloud

Обмеження розміру для одного запиту

За можливості тримайте файли для завантаження одним запитом меншими за 100 MB.

Для цих каналів скрипт має явні пороги блокування одиночного /upload:

Канал	Обмеження одного запиту
Telegram	20 MiB
Discord	10 MiB
S3	64 MiB
WebDAV	64 MiB
GitHub Releases	64 MiB
GitLab Packages	64 MiB

Коли файл перевищує одне з цих обмежень, скрипт повідомляє відповідну помилку локально. Інші канали не мають жорстко заданої локальної перевірки 100 MB у скрипті. Якщо тіло запиту перевищує можливості Cloudflare або платформи, помилку поверне Cloudflare або віддалена платформа.

Частинне завантаження

Скрипт частинного завантаження спочатку просить сервер визначити цільовий файл, а потім виконує потік для великих файлів вибраного каналу. Вам не потрібно самостійно писати запити створення сесії частин, об'єднання або завершення.

node imghost-token-chunk-upload.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --file "D:\test\video.zip" `
  --channel github `
  --folder "photos/2026" `
  --concurrency 3

Параметри частинного завантаження

Параметр	Обов'язково	Опис
--base-url <url>	Так	URL сайту ImgHost.
--token <token>	Так	API Token. Також можна використати змінну середовища IMGHOST_API_TOKEN.
--file <path>	Так	Шлях до локального файлу.
--channel <key>	Так	Канал завантаження.
--folder <path>	Ні	Папка завантаження.
--name-type <type>	Ні	Режим іменування, зіставлений із серверним uploadNameType. Типово default.
--channel-name <name>	Ні	Вибирає дочірній канал або акаунт. Якщо пропущено, вирішує серверна конфігурація каналу.
--concurrency <n>	Ні	Паралельні завантаження. Типово 1, максимум 3.
--retries <n>	Ні	Кількість повторів для тимчасових помилок. Типово 3.
--timeout-ms <n>	Ні	Тайм-аут кожного запиту. Типово 180000.
--output <pretty|json>	Ні	Формат виводу. Типово pretty.
--save-response <path>	Ні	Зберегти фінальну JSON-відповідь у файл.
--list-channels	Ні	Показати канали, доступні поточному token, і завершити роботу.

Канали частинного завантаження

Key каналу	Потік завантаження
telegram / tg	Справжня частинна сесія /upload
discord / dc	Справжня частинна сесія /upload
cfr2 / r2	Справжня частинна сесія /upload
github / gh	Справжня частинна сесія /upload
gitlab / gl	Справжня частинна сесія /upload
webdav / wd	Справжня частинна сесія /upload
s3	S3 multipart upload
onedrive / od	Сесія завантаження OneDrive
googledrive / google / gd	Відновлюване завантаження Google Drive
dropbox / db	Сесія завантаження Dropbox
yandex / yx	Прямий URL завантаження Yandex
pcloud / pd	Посилання завантаження pCloud
huggingface / hf	Завантаження Hugging Face LFS

Зразки зі стисненими файлами Yandex були нестабільними під час тестування. Успішне завантаження нестиснених файлів підтверджено.

Відповідь після завантаження

Після успішного завантаження скрипт виводить:

success
src: /file/photos/2026/example.png
url: https://your-domain/file/photos/2026/example.png
fileId: photos/2026/example.png

Поле	Опис
src	Внутрішній шлях файла на сайті.
url	Повний публічний URL, придатний для ваших скриптів або записів бази даних.
fileId	ID файла, корисний для подальших запитів, керування або журналів.
channelName	Частинний скрипт може повернути фактично використаний дочірній канал або акаунт.

З --output json скрипт виводить повну JSON-відповідь для програмного використання.

Прямий API-виклик одного запиту

Якщо ви не використовуєте скрипт, кінцеву точку завантаження одним запитом можна викликати напряму:

POST https://your-domain/upload?uploadChannel=s3&uploadFolder=photos/2026&uploadNameType=default
Authorization: Bearer your API Token
Content-Type: multipart/form-data

Поле форми:

Поле	Обов'язково	Опис
file	Так	Файл для завантаження.

Параметри запиту:

Параметр	Обов'язково	Опис
uploadChannel	Так	Реальний канал завантаження.
uploadFolder	Ні	Папка завантаження.
uploadNameType	Ні	Режим іменування.
channelName	Ні	Вибирає дочірній канал або акаунт.

Успішні відповіді мають такий вигляд:

{
  "success": true,
  "src": "/file/photos/2026/example.png",
  "url": "https://your-domain/file/photos/2026/example.png",
  "fileId": "photos/2026/example.png"
}

FAQ

Великі завантаження одним запитом не проходять

Одиночний /upload надсилає весь файл одним запитом. Великі файли можуть бути заблоковані Cloudflare або віддаленою платформою. Для великих файлів використовуйте скрипт частинного завантаження.

--channel-name задано, але завантаження все одно не проходить

Перевірте, що у вибраному каналі справді є дочірній канал із такою назвою і що він увімкнений. Якщо --channel-name пропущено, сервер вибирає доступний акаунт відповідно до конфігурації цього каналу.

Я хочу використати результат в іншій програмі

Використовуйте --output json або додайте --save-response result.json. Прочитайте поле url, щоб отримати повний URL файла.

Yandex не може завантажувати архіви

Yandex не підтримує архівні формати. Це може бути зумовлено політикою платформи. Під час використання Yandex за можливості завантажуйте неархівні файли.