Загрузка файлов через 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 не требуются. Ответ содержит канал загрузки по умолчанию, ключи каналов, имена дочерних каналов и состояние балансировки нагрузки. Секреты, токены обновления и другие чувствительные значения конфигурации не возвращаются.

Выбор режима загрузки

Режим	Когда использовать	Описание
Загрузка одним запросом	Небольшие файлы, простые скрипты, проверка соединения	Отправляет весь файл в /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	Нет	Вывести каналы, доступные текущему API Token, и завершить работу.

Каналы для загрузки одним запросом

Ключ канала	Канал
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	Нет	Вывести каналы, доступные текущему API Token, и завершить работу.

Каналы для загрузки частями

Ключ канала	Поток загрузки
telegram / tg	Настоящая сессия загрузки частями через /upload
discord / dc	Настоящая сессия загрузки частями через /upload
cfr2 / r2	Настоящая сессия загрузки частями через /upload
github / gh	Настоящая сессия загрузки частями через /upload
gitlab / gl	Настоящая сессия загрузки частями через /upload
webdav / wd	Настоящая сессия загрузки частями через /upload
s3	Многочастная загрузка S3
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 по возможности загружайте неархивные файлы.