آپلود فایل با API Token

آپلود فایل با API Token برای اسکریپت‌ها، کارهای خودکار و برنامه‌های بیرونی مناسب است. نیازی نیست صفحه ImgHost را در مرورگر باز کنید؛ کافی است نشانی سایت، API Token، مسیر فایل محلی و یک کانال واقعی آپلود را بدهید. پس از موفقیت، اسکریپت لینک فایل را برمی‌گرداند.

ویرایش API Token

آماده‌سازی

در پنل مدیریت باز کنید:

text

System Settings -> Security Settings -> API Token

هنگام ساخت یا ویرایش API Token، مطمئن شوید مجوز آپلود فعال است و کانال پیش‌فرض نیز یک کانال واقعی است. آپلود با API Token از توزیع هوشمند استفاده نمی‌کند؛ بنابراین در اسکریپت __smart__ نفرستید. از کلید کانال واقعی مانند s3، github یا telegram استفاده کنید.

دانلود اسکریپت‌های آپلود

مستندات ImgHost دو اسکریپت Node.js دارد:

اسکریپت	کاربرد
اسکریپت آپلود با یک درخواست	فقط یک بار `/upload` را فراخوانی می‌کند؛ مناسب فایل‌های کوچک و آزمون اتصال رابط
اسکریپت آپلود بخش‌بخش	بسته به کانال از آپلود بخش‌بخش، آپلود مستقیم یا نشست پلتفرم استفاده می‌کند؛ مناسب فایل‌های بزرگ

برای اجرا، Node.js 18 یا نسخه جدیدتر لازم است.

دیدن کانال‌های قابل استفاده

هر دو اسکریپت می‌توانند پیش از آپلود، کانال‌های قابل استفاده برای API Token فعلی را نشان دهند:

powershell

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 می‌فرستد:

powershell

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"

API Token را می‌توان در متغیر محیطی هم قرار داد:

powershell

$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>`	بله	نشانی سایت 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`	خیر	فقط کانال‌ها را نشان می‌دهد و فایلی آپلود نمی‌کند

کلیدهای کانال

کلید کانال	کانال
`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 باشد. کانال‌های زیر در اسکریپت محدودیت محلی روشن دارند:

کانال	حد بالا
Telegram	20 MiB
Discord	10 MiB
S3	64 MiB
WebDAV	64 MiB
GitHub Releases	64 MiB
GitLab Packages	64 MiB

اگر فایل از حد بگذرد، اسکریپت پیش از ارسال درخواست خطای محلی نشان می‌دهد. برای کانال‌های دیگر، اسکریپت حد محلی ثابت 100 MB نمی‌گذارد؛ اگر درخواست بیش از توان Cloudflare یا پلتفرم مقصد باشد، خطا از همان‌جا برمی‌گردد.

آپلود بخش‌بخش

اسکریپت آپلود بخش‌بخش ابتدا با API Token از سمت سرور می‌خواهد مقصد آپلود را تعیین کند، سپس مسیر فایل بزرگ مربوط به کانال انتخاب‌شده را اجرا می‌کند. کاربر لازم نیست خودش نشست بسازد، بخش‌ها را بفرستد، فایل را ادغام کند یا درخواست تکمیل بنویسد.

powershell

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>`	بله	نشانی سایت 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`	خیر	فقط کانال‌ها را نشان می‌دهد و آپلود انجام نمی‌دهد

مسیرهای آپلود بخش‌بخش

کلید کانال	مسیر آپلود
`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`	لینک آپلود مستقیم Yandex
`pcloud` / `pd`	لینک آپلود pCloud
`huggingface` / `hf`	آپلود Hugging Face LFS

در آزمایش‌ها، فایل‌های آرشیوی یا فشرده روی Yandex قابل اتکا نبودند. هنگام استفاده از کانال Yandex، فایل غیرآرشیوی انتخاب کنید.

نتیجه

پس از آپلود موفق، اسکریپت نتیجه‌ای شبیه این نشان می‌دهد:

text

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

فیلد	توضیح
`src`	مسیر داخلی فایل در سایت
`url`	لینک کامل دسترسی، مناسب برای ذخیره مستقیم در اسکریپت یا پایگاه داده
`fileId`	شناسه فایل برای جست‌وجو، مدیریت یا ثبت بعدی
`channelName`	در آپلود بخش‌بخش ممکن است کانال فرعی یا حساب واقعاً استفاده‌شده را نشان دهد

با --output json، اسکریپت JSON کامل را چاپ می‌کند تا برنامه‌ها راحت‌تر آن را پردازش کنند.

فراخوانی مستقیم رابط تک‌درخواستی

بدون اسکریپت هم می‌توان رابط آپلود با یک درخواست را مستقیم فراخوانی کرد:

text

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`	خیر	کانال فرعی یا حساب مشخص

در صورت موفقیت، رابط نتیجه‌ای شبیه این برمی‌گرداند:

json

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

پرسش‌های رایج

فایل بزرگ در آپلود با یک درخواست موفق نمی‌شود

در /upload تک‌درخواستی، کل فایل در یک درخواست فرستاده می‌شود. فایل بزرگ ممکن است به محدودیت Cloudflare، حافظه Worker یا پلتفرم مقصد برخورد کند. برای فایل‌های بزرگ از اسکریپت آپلود بخش‌بخش استفاده کنید.

با `--channel-name` هم خطا می‌گیرم

بررسی کنید در آن کانال، کانال فرعی با همان نام دقیق وجود داشته باشد و فعال باشد. اگر --channel-name ندهید، سمت سرور بر اساس تنظیمات کانال یک حساب در دسترس انتخاب می‌کند.

می‌خواهم نتیجه را در برنامه دیگری استفاده کنم

از --output json یا --save-response result.json استفاده کنید. برنامه می‌تواند فیلد url را بخواند و لینک کامل فایل را بگیرد.

آپلود آرشیو در Yandex شکست می‌خورد

Yandex از قالب‌های آرشیوی یا فشرده به شکل قابل اتکا پشتیبانی نمی‌کند و ممکن است این موضوع به سیاست‌های پلتفرم مربوط باشد. برای Yandex از فایل غیرآرشیوی استفاده کنید.

آپلود فایل با API Token ​

آماده‌سازی ​

دانلود اسکریپت‌های آپلود ​

دیدن کانال‌های قابل استفاده ​

انتخاب روش آپلود ​

آپلود با یک درخواست ​

پارامترهای آپلود با یک درخواست ​

کلیدهای کانال ​

محدودیت اندازه در آپلود با یک درخواست ​

آپلود بخش‌بخش ​

پارامترهای آپلود بخش‌بخش ​

مسیرهای آپلود بخش‌بخش ​

نتیجه ​

فراخوانی مستقیم رابط تک‌درخواستی ​

پرسش‌های رایج ​

فایل بزرگ در آپلود با یک درخواست موفق نمی‌شود ​

با --channel-name هم خطا می‌گیرم ​

می‌خواهم نتیجه را در برنامه دیگری استفاده کنم ​

آپلود آرشیو در Yandex شکست می‌خورد ​

آپلود فایل با API Token

آماده‌سازی

دانلود اسکریپت‌های آپلود

دیدن کانال‌های قابل استفاده

انتخاب روش آپلود

آپلود با یک درخواست

پارامترهای آپلود با یک درخواست

کلیدهای کانال

محدودیت اندازه در آپلود با یک درخواست

آپلود بخش‌بخش

پارامترهای آپلود بخش‌بخش

مسیرهای آپلود بخش‌بخش

نتیجه

فراخوانی مستقیم رابط تک‌درخواستی

پرسش‌های رایج

فایل بزرگ در آپلود با یک درخواست موفق نمی‌شود

با `--channel-name` هم خطا می‌گیرم

می‌خواهم نتیجه را در برنامه دیگری استفاده کنم

آپلود آرشیو در Yandex شکست می‌خورد