مستندات API نابغه فایل

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

Base URL: https://nabeghefile.ir · نسخه‌ی 1.5.0 · OpenAPI 3.1 (برای Postman / Swagger)

شروع سریع

کد ورود بگیرید: POST /panel/api/v1/auth/otp/request با {"phone": "09..."}
کد را تأیید کنید و توکن بگیرید: POST /panel/api/v1/auth/otp/verify → token
در همه‌ی درخواست‌ها هدر Authorization: Bearer <token> را بفرستید.

BASE=https://nabeghefile.ir
curl -X POST "$BASE/panel/api/v1/auth/otp/request" -H "Content-Type: application/json" -d '{"phone":"09121234567"}'
TOKEN=$(curl -s -X POST "$BASE/panel/api/v1/auth/otp/verify" -H "Content-Type: application/json" \
  -d '{"phone":"09121234567","code":"123456"}' | jq -r .token)
curl "$BASE/panel/api/v1/files" -H "Authorization: Bearer $TOKEN"

همه‌ی پاسخ‌ها JSON هستند و فیلد ok دارند. در خطا، msg یک پیام فارسیِ قابل نمایش به کاربر است.

احراز هویت

نوع توکن	از کجا	اعتبار	کاربرد
JWT اپ	ورود با کد یک‌بارمصرف (بالا)	۳۰ روز	اپ موبایل، وب‌سایت‌ها و همه‌ی endpointها
توکن همگام‌سازی	پنل ← همگام‌سازی دسکتاپ	تا ساخت توکن جدید	اسکریپت‌ها و سرورها: همگام‌سازی، پردازش هوشمند، کیف‌پول، دانلود
توکن بکاپ	پنل ← بکاپ‌گیری خودکار	تا ساخت توکن جدید	فقط آپلود بکاپ

کنار هر endpoint نوع توکن قابل قبول آن نوشته شده. توکن را مثل رمز عبور نگه دارید؛ اگر لو رفت از همان صفحه‌ی پنل توکن جدید بسازید تا قبلی باطل شود.

خطاها

{"ok": false, "msg": "موجودی کیف‌پول هوش مصنوعی کافی نیست (حداقل ۳٬۰۰۰ تومان).", "code": "insufficient_balance"}

HTTP	code	معنی
401	—	توکن ندارد، نامعتبر یا منقضی است
400	invalid_params	پارامتر نامعتبر یا ناشناخته
400	unsupported_file_type	این عملیات برای نوع این فایل نیست
400	file_encrypted	فایل رمزنگاری‌شده سمت سرور قابل پردازش نیست
400	file_too_large	حجم فایل بیشتر از سقف پردازش است
401	unauthorized	توکن ندارد، نامعتبر یا منقضی است
400	invalid_size	انتقال مستقیم: حجم فایل ارسال نشده یا نامعتبر است
400	quota_exceeded	انتقال مستقیم: فضای کافی نیست
403	invalid_token	انتقال مستقیم: توکن آپلود نامعتبر یا منقضی است
403	purpose_not_allowed	انتقال مستقیم: purpose برای این نوع توکن مجاز نیست
409	upload_not_found	انتقال مستقیم: فایل روی سرور ذخیره‌سازی پیدا نشد (قدم ۲ انجام نشده یا ناموفق بوده)
503	direct_unavailable	سرور انتقال موقتاً در دسترس نیست — از مسیر پشتیبان (fallback) استفاده کنید
402	insufficient_balance	موجودی کیف‌پول هوش مصنوعی کافی نیست
404	file_not_found	فایل وجود ندارد یا متعلق به شما نیست
404	unknown_operation	عملیات وجود ندارد یا غیرفعال است
404	job_not_found	پردازش وجود ندارد یا متعلق به شما نیست
409	job_finished	پردازش تمام شده و قابل لغو نیست
429	too_many_active_jobs	سقف پردازش هم‌زمان پر است
429	daily_free_limit	سقف پردازش‌های رایگان امروز پر است
503	processing_disabled	پردازش هوشمند موقتاً غیرفعال است
503	engine_not_configured	موتور هوش مصنوعی هنوز راه‌اندازی نشده

فیلد code در endpointهای پردازش هوشمند همیشه هست و پایدار است — منطق برنامه‌تان را روی code بنویسید، نه روی متن msg.

راهنمای پردازش هوشمند

هر پردازش روی یکی از فایل‌های خود کاربر انجام می‌شود و نتیجه‌اش هم در پاسخ API و هم به‌صورت فایل در فضای کاربر ذخیره می‌شود. روند کار:

GET /processing/operations — عملیات، پارامترها و قیمت‌های لحظه‌ای را بخوانید.
POST /files/{file_id}/process — پردازش را در صف بگذارید (پاسخ فوری 201).
GET /processing/jobs/{job_id} را هر ۲ تا ۵ ثانیه بخوانید تا status یکی از succeeded، failed یا canceled شود.
نتیجه در result و فایل‌های ساخته‌شده در outputs[].download_url (با همان توکن قابل دانلود).

پول کاربر امن است: هنگام ثبت پردازش هیچ مبلغی کسر نمی‌شود. قیمت دقیق (مثلاً بر اساس مدت واقعی صوت، گردشده به بالا تا دقیقه‌ی کامل) درست قبل از مرحله‌ی پولی کسر می‌شود و اگر پردازش به هر دلیلی ناموفق یا لغو شود، کل مبلغ خودکار به کیف‌پول برمی‌گردد. همه‌ی حرکت‌ها در GET /ai/wallet قابل مشاهده‌اند.

# ۱) ثبت پردازش: تبدیل گفتار به متن + زیرنویس
JOB=$(curl -s -X POST "$BASE/panel/api/v1/files/42/process" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"operation":"media_transcribe","params":{"language":"fa"}}' | jq -r .job.id)
# ۲) پیگیری تا پایان
while :; do R=$(curl -s "$BASE/panel/api/v1/processing/jobs/$JOB" -H "Authorization: Bearer $TOKEN")
  S=$(echo "$R" | jq -r .job.status); echo "$S $(echo "$R" | jq -r .job.progress)%"
  [ "$S" = queued ] || [ "$S" = running ] || break; sleep 3; done
# ۳) نتیجه و دانلود زیرنویس
echo "$R" | jq '.job.result.text, .job.outputs'

عملیات فعال (لحظه‌ای)

operation	عملیات	فایل‌ها	پارامترها	قیمت (تومان)	خروجی
image_describe	توصیف هوشمند تصویر	image	language (fa \| en \| ar \| tr \| de \| fr \| es \| ru) پیش‌فرض: fa	300	شرح، متن جایگزین (alt) و برچسب‌ها
image_ocr	استخراج متن از تصویر (OCR)	image	save_txt پیش‌فرض: True	300	متن استخراج‌شده + فایل .txt
image_convert	تبدیل فرمت تصویر	image	format (jpg \| png \| webp) پیش‌فرض: webp quality 1–100 پیش‌فرض: 85	رایگان	فایل تصویرِ جدید
image_resize	تغییر اندازه تصویر	image	max_width 16–8000 پیش‌فرض: 1280 max_height 16–8000 پیش‌فرض: 1280	رایگان	فایل تصویرِ تغییر اندازه‌یافته
image_compress	فشرده‌سازی تصویر	image	quality 1–100 پیش‌فرض: 75	رایگان	تصویرِ کم‌حجم‌شده
media_transcribe	تبدیل گفتار به متن + زیرنویس	audio، video	language (auto \| fa \| en \| ar \| tr \| de \| fr \| es \| ru) پیش‌فرض: auto	3,000 هر دقیقه (حداقل 1,500)	متن کامل + فایل زیرنویس .srt + فایل .txt
media_summarize	خلاصه‌ی هوشمند صوت و ویدیو	audio، video	language (auto \| fa \| en \| ar \| tr \| de \| fr \| es \| ru) پیش‌فرض: auto summary_language (fa \| en \| ar \| tr \| de \| fr \| es \| ru) پیش‌فرض: fa	3,000 هر دقیقه + 500 (حداقل 2,000)	خلاصه، نکات کلیدی، متن کامل و زیرنویس
video_thumbnail	ساخت تصویر کاور ویدیو	video	at_percent 0–99 پیش‌فرض: 10	رایگان	تصویر JPG
media_extract_audio	جداسازی صدا از ویدیو	video	bitrate (64k \| 128k \| 192k) پیش‌فرض: 128k	رایگان	فایل MP3
video_convert	تبدیل و کم‌حجم‌کردن ویدیو	video	resolution (480p \| 720p) پیش‌فرض: 720p	300 هر دقیقه (حداقل 300)	ویدیوی MP4
doc_summarize	خلاصه‌ی هوشمند سند	document	summary_language (fa \| en \| ar \| tr \| de \| fr \| es \| ru) پیش‌فرض: fa	40 هر ۱۰۰۰ کاراکتر + 300 (حداقل 300)	خلاصه و نکات کلیدی
doc_translate	ترجمه‌ی سند	document	target_language (fa \| en \| ar \| tr \| de \| fr \| es \| ru) پیش‌فرض: fa	120 هر ۱۰۰۰ کاراکتر + 300 (حداقل 500)	فایل متنیِ ترجمه‌شده

محدودیت‌ها: حداکثر حجم ورودی 500 مگابایت · صوت/ویدیو تا 90 دقیقه · تبدیل ویدیو تا 10 دقیقه و 300 مگابایت · اسناد تا 120,000 کاراکتر · 5 پردازش هم‌زمان · 50 پردازش رایگان در روز. فایل‌های رمزنگاری‌شده سمت سرور قابل پردازش نیستند.

احراز هویت

ورود بدون رمز با کد یک‌بارمصرف و دریافت توکن JWT.

POST/panel/api/v1/auth/otp/request

درخواست کد ورود

یک کد ۶ رقمی به موبایل (پیامک) یا ایمیل می‌فرستد. کد ۲ دقیقه اعتبار دارد و بین دو درخواست برای یک شماره حداقل ۶۰ ثانیه فاصله لازم است.

احراز هویت: بدون نیاز به توکن

بدنه: application/json

فیلد	نوع	توضیح
phone	string
email	string

{
  "phone": "09121234567"
}

پاسخ	شرح
200	کد ارسال شد
400	ورودی نامعتبر یا ارسال پیاپی (فیلد wait = ثانیه‌ی باقی‌مانده)

POST/panel/api/v1/auth/otp/verify

تأیید کد و دریافت توکن

اگر کد درست باشد یک توکن JWT با اعتبار ۳۰ روز برمی‌گرداند؛ اولین ورود موفق، حساب را خودکار می‌سازد. توکن را در هدر Authorization: Bearer بفرستید.

احراز هویت: بدون نیاز به توکن

بدنه: application/json

فیلد	نوع	توضیح
phone	string
email	string
code	string

{
  "code": "123456",
  "phone": "09121234567"
}

پاسخ	شرح
200	ورود موفق
400	کد اشتباه/منقضی یا ورودی ناقص

انتقال مستقیم (پیشنهادی)

اولویت اول آپلود و دانلود: بایت‌های فایل مستقیم با سرور انتقال (رله) جابه‌جا می‌شوند — بدون عبور از Cloudflare و پنل، بدون سقف ۱۰۰ مگابایتی هر درخواست، با پشتیبانی از Range/ادامه‌ی دانلود. مسیرهای قدیمی آپلود به‌عنوان پشتیبان باقی هستند.

POST/panel/api/v1/uploads/authorize

۱) مجوز آپلود مستقیم

قدم اول آپلود. پاسخ شامل upload.url (روی سرور انتقال) و upload.headers است. قدم دوم — بدون توکن Bearer: POST {upload.url} به‌صورت multipart با فیلد file و هدر X-Upload-Token؛ پاسخ سرور انتقال {ok, size, sha256, receipt} است. قدم سوم: همین مقادیر را به /uploads/confirm بفرستید. purpose: با توکن اپ files (پیش‌فرض) یا sync؛ با توکن همگام‌سازی sync (پیش‌فرض) یا files؛ با توکن بکاپ فقط backup. در sync اگر sha256 بفرستید و محتوا تغییری نکرده باشد unchanged=true برمی‌گردد. اگر سرور انتقال در دسترس نباشد 503 با code=direct_unavailable و فیلد fallback (مسیر قدیمی) برمی‌گردد.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار) — یا — توکن همگام‌سازی — پنل → همگام‌سازی دسکتاپ (بدون انقضا) — یا — توکن بکاپ خودکار — پنل → بکاپ‌گیری خودکار (بدون انقضا)

بدنه: application/json

فیلد	نوع	توضیح
filename	string
size	integer	بایت
sha256	string	اختیاری — برای تشخیص بدون تغییر در sync
purpose	string (files \| sync \| backup)

{
  "filename": "\u06af\u0632\u0627\u0631\u0634.pdf",
  "purpose": "files",
  "size": 734003200
}

پاسخ	شرح
200	مجوز صادر شد
400	حجم نامعتبر یا فضای ناکافی (quota_exceeded)
401	توکن نامعتبر
403	purpose برای این توکن مجاز نیست
503	مسیر مستقیم موقتاً در دسترس نیست — از fallback استفاده کنید

AUTH="Authorization: Bearer $TOKEN"; F=video.mp4
A=$(curl -s -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"filename\":\"$F\",\"size\":$(stat -c%s "$F")}" $BASE/panel/api/v1/uploads/authorize)
R=$(curl -s -H "X-Upload-Token: $(echo $A | jq -r .token)" -F "file=@$F" "$(echo $A | jq -r .upload.url)")
curl -s -H "$AUTH" -H "Content-Type: application/json" $BASE/panel/api/v1/uploads/confirm \
  -d "$(jq -n --argjson a "$A" --argjson r "$R" --arg f "$F" \
      '{token:$a.token, upload_id:$a.upload_id, filename:$f, size:$r.size, sha256:$r.sha256, receipt:$r.receipt}')"

POST/panel/api/v1/uploads/confirm

۲) ثبت نهایی آپلود مستقیم

بعد از پاسخ موفق سرور انتقال. size/sha256/receipt را عیناً از پاسخ سرور انتقال بفرستید (رسید امضاشده — هش بدون دانلود دوباره ثبت می‌شود). تکرار امن است: confirm دوباره همان فایل را با already_confirmed=true برمی‌گرداند. توکن تا ۲۴ ساعت بعد از انقضا برای confirm پذیرفته می‌شود.

بدنه: application/json

فیلد	نوع	توضیح
token	string
upload_id	string
filename	string
purpose	string (files \| sync \| backup)
size	integer
sha256	string
receipt	string
mime_type	string
is_encrypted	boolean

پاسخ	شرح
200	ثبت شد
400	فضای ناکافی (فایل آپلودشده پاک می‌شود)
403	توکن آپلود نامعتبر
409	فایل روی سرور پیدا نشد (upload_not_found)

GET/panel/api/v1/files/{file_id}/direct-link

لینک دانلود مستقیم

یک لینک امضاشده‌ی ۶ ساعته روی سرور انتقال برمی‌گرداند که بدون توکن قابل دانلود است و از Range (ادامه‌ی دانلود، دانلود چندتکه، پخش و جلو/عقب کردن ویدیو) پشتیبانی می‌کند. inline=1 برای نمایش در مرورگر/پلیر.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار) — یا — توکن همگام‌سازی — پنل → همگام‌سازی دسکتاپ (بدون انقضا)

پارامتر	محل	نوع	الزامی	توضیح
file_id	مسیر	integer	بله	شناسه‌ی فایل
inline	query	integer	خیر	1 = نمایش به‌جای دانلود

پاسخ	شرح
200	لینک
404	فایل پیدا نشد
503	مسیر مستقیم در دسترس نیست (fallback_url)

حساب و داشبورد

پروفایل، آمار کلی و وضعیت فضا.

GET/panel/api/v1/user/profile

پروفایل کاربر

اطلاعات حساب و وضعیت فضای ذخیره‌سازی.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پاسخ	شرح
200	پروفایل
401	توکن نامعتبر

GET/panel/api/v1/dashboard

داشبورد

همان آمار صفحه‌ی داشبورد پنل: فضا، تعداد فایل/لینک/صفحه، دانلودها، تیکت‌ها و آخرین موارد.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پاسخ	شرح
200	آمار
401	توکن نامعتبر

فایل‌ها

فهرست، جست‌وجوی تمام‌متن، آپلود، دانلود و حذف فایل‌ها.

GET/panel/api/v1/files

فهرست فایل‌ها

فایل‌های کاربر (به‌جز سطل بازیافت)، جدیدترین اول. با search جست‌وجو در نام و «محتوای» فایل‌ها (تمام‌متن) انجام می‌شود.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
page	query	integer	خیر	شماره‌ی صفحه (پیش‌فرض ۱)
per_page	query	integer	خیر	تعداد در هر صفحه (پیش‌فرض ۲۰)
search	query	string	خیر	جست‌وجوی تمام‌متن
type	query	string	خیر	فیلتر بخشی از mime type، مثل image یا video

پاسخ	شرح
200	فهرست
401	توکن نامعتبر

POST/panel/api/v1/files/upload

آپلود فایل

مسیر پشتیبان آپلود از طریق پنل (multipart/form-data، فیلد file) — حداکثر ۱۰۰ مگابایت در هر درخواست. اولویت اول: /uploads/authorize (انتقال مستقیم، بدون این محدودیت).

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

بدنه: multipart/form-data

فیلد	نوع	توضیح
file	string (فایل)

پاسخ	شرح
200	آپلود شد
400	فایلی ارسال نشده یا فضای کافی نیست
401	توکن نامعتبر
500	سرور ذخیره‌سازی در دسترس نیست

GET/panel/api/v1/files/{file_id}/download

دانلود فایل

با توکن JWT یا توکن همگام‌سازی. اولویت اول: پاسخ 302 به لینک امضاشده‌ی سرور انتقال (Range دارد) — کلاینت باید redirect را دنبال کند (curl -L؛ requests/OkHttp/fetch خودکار). اگر سرور انتقال در دسترس نباشد یا via=panel بفرستید، فایل از پنل stream می‌شود.

پارامتر	محل	نوع	الزامی	توضیح
file_id	مسیر	integer	بله	شناسه‌ی فایل
via	query	string	خیر	panel = اجبار مسیر پشتیبان
inline	query	integer	خیر	1 = نمایش به‌جای دانلود (فقط در مسیر مستقیم)

پاسخ	شرح
302	انتقال به لینک دانلود مستقیم (Location)
200	محتوای فایل (باینری)
401	توکن نامعتبر
404	فایل پیدا نشد

DELETE/panel/api/v1/files/{file_id}

حذف فایل (انتقال به سطل بازیافت)

فایل به سطل بازیافت می‌رود و تا ۳۰ روز از پنل قابل بازگردانی است؛ بعد از آن به‌طور خودکار و کامل پاک می‌شود.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
file_id	مسیر	integer	بله	شناسه‌ی فایل

پاسخ	شرح
200	حذف شد
401	توکن نامعتبر
404	فایل یافت نشد

پردازش هوشمند

هوش مصنوعی و ابزارهای رسانه‌ای روی فایل‌ها: گفتار به متن و زیرنویس، توصیف و OCR تصویر، خلاصه و ترجمه‌ی اسناد، تبدیل و فشرده‌سازی.

GET/panel/api/v1/processing/operations

فهرست عملیات پردازش

عملیات فعال، نوع فایل‌های مجاز، پارامترها، قیمت دقیق و محدودیت‌ها — همیشه از همین endpoint بخوانید (قیمت‌ها از پنل مدیریت قابل تغییرند).

پارامتر	محل	نوع	الزامی	توضیح
file_kind	query	string	خیر	فقط عملیات یک نوع فایل: image، audio، video یا document

پاسخ	شرح
200	فهرست
400	file_kind نامعتبر
401	توکن نامعتبر

POST/panel/api/v1/files/{file_id}/process

شروع پردازش یک فایل

یک پردازش در صف می‌گذارد و بلافاصله (201) برمی‌گرداند — هیچ مبلغی در این لحظه کسر نمی‌شود. Worker ورودی را بررسی می‌کند، قیمت دقیق را (مثلاً بر اساس مدت واقعی صوت) حساب و درست قبل از مرحله‌ی پولی کسر می‌کند؛ اگر پردازش به هر دلیلی ناموفق یا لغو شود، کل مبلغ خودکار برمی‌گردد. وضعیت را با GET /processing/jobs/{job_id} دنبال کنید. خروجی‌ها در فضای کاربر هم ذخیره می‌شوند.

پارامتر	محل	نوع	الزامی	توضیح
file_id	مسیر	integer	بله	شناسه‌ی فایل ورودی

بدنه: application/json

فیلد	نوع	توضیح
operation	string	شناسه‌ی عملیات (از /processing/operations)
params	object	پارامترهای همان عملیات؛ مقادیر نفرستاده = پیش‌فرض

{
  "operation": "media_transcribe",
  "params": {
    "language": "fa"
  }
}

پاسخ	شرح
201	در صف قرار گرفت
400	ورودی نامعتبر — code: invalid_params، unsupported_file_type، file_encrypted، file_too_large
401	توکن نامعتبر
402	موجودی کافی نیست — code: insufficient_balance
404	فایل یا عملیات پیدا نشد — code: file_not_found، unknown_operation
429	سقف پردازش هم‌زمان یا رایگانِ روزانه — code: too_many_active_jobs، daily_free_limit
503	پردازش غیرفعال است — code: processing_disabled، engine_not_configured

curl -X POST "$BASE/panel/api/v1/files/42/process" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"operation":"media_transcribe","params":{"language":"fa"}}'

GET/panel/api/v1/processing/jobs

فهرست پردازش‌ها

پردازش‌های کاربر، جدیدترین اول.

پارامتر	محل	نوع	الزامی	توضیح
status	query	string	خیر	queued، running، succeeded، failed یا canceled
file_id	query	integer	خیر	فقط پردازش‌های یک فایل
page	query	integer	خیر	پیش‌فرض ۱
per_page	query	integer	خیر	پیش‌فرض ۲۰، حداکثر ۱۰۰

پاسخ	شرح
200	فهرست
400	status نامعتبر
401	توکن نامعتبر

GET/panel/api/v1/processing/jobs/{job_id}

وضعیت و نتیجه‌ی یک پردازش

تا وقتی status برابر queued یا running است هر ۲ تا ۵ ثانیه دوباره بخوانید. progress (۰ تا ۱۰۰) و stage پیشرفت را نشان می‌دهند. در succeeded، result نتیجه‌ی ساختاری و outputs فایل‌های ساخته‌شده (با download_url قابل دانلود با همین توکن) است.

پارامتر	محل	نوع	الزامی	توضیح
job_id	مسیر	string	بله	شناسه‌ی پردازش

پاسخ	شرح
200	پردازش
401	توکن نامعتبر
404	پیدا نشد — code: job_not_found

curl "$BASE/panel/api/v1/processing/jobs/9f2c4e1a7b3d5c60" -H "Authorization: Bearer $TOKEN"

POST/panel/api/v1/processing/jobs/{job_id}/cancel

لغو پردازش

پردازشِ در صف فوراً لغو می‌شود؛ پردازشِ در حال اجرا در اولین مرحله‌ی ممکن متوقف و مبلغش برگردانده می‌شود.

پارامتر	محل	نوع	الزامی	توضیح
job_id	مسیر	string	بله	شناسه‌ی پردازش

پاسخ	شرح
200	لغو شد / درخواست لغو ثبت شد
404	پیدا نشد
409	پردازش تمام شده — code: job_finished

کیف‌پول هوش مصنوعی

موجودی و ریز تراکنش‌های کیف‌پول هوش مصنوعی.

GET/panel/api/v1/ai/wallet

کیف‌پول هوش مصنوعی

موجودی (تومان) و آخرین تراکنش‌ها: کسر بابت پردازش، بازگشت وجه، شارژ و استفاده از تحلیل/پرسش.

پارامتر	محل	نوع	الزامی	توضیح
limit	query	integer	خیر	تعداد تراکنش (پیش‌فرض ۲۰، حداکثر ۱۰۰)

پاسخ	شرح
200	کیف‌پول
401	توکن نامعتبر

لینک‌های دانلود

ساخت و مدیریت لینک کوتاه، رمزنگاری‌شده و اختصاصی.

GET/panel/api/v1/links

فهرست لینک‌ها

لینک‌های دانلود کاربر.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
page	query	integer	خیر	پیش‌فرض ۱
per_page	query	integer	خیر	پیش‌فرض ۲۰

پاسخ	شرح
200	فهرست
401	توکن نامعتبر

POST/panel/api/v1/links

ساخت لینک دانلود

لینک برای یک یا چند فایل (فایل‌های سطل بازیافت مجاز نیستند). short = آدرس کوتاه، encrypted = توکن ۴۰ کاراکتری غیرقابل‌حدس، custom = آدرس دلخواه (custom_slug الزامی). رمز و تاریخ انقضا اختیاری‌اند. برای چند فایل، download_url دانلود ZIP است.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

بدنه: application/json

فیلد	نوع	توضیح
file_ids	array
name	string
link_type	string (short \| encrypted \| custom)	پیش‌فرض: short
password	string
expires_days	integer
custom_slug	string
domain_id	integer
zip_paths	object	file_id → مسیر داخل ZIP

{
  "expires_days": 7,
  "file_ids": [
    42,
    43
  ],
  "link_type": "encrypted",
  "password": "1234"
}

پاسخ	شرح
200	ساخته شد
400	ورودی نامعتبر یا آدرس تکراری/رزرو
401	توکن نامعتبر

DELETE/panel/api/v1/links/{link_id}

حذف لینک

حذف یک لینک دانلود (فایل‌ها حذف نمی‌شوند).

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
link_id	مسیر	integer	بله	شناسه‌ی لینک

پاسخ	شرح
200	حذف شد
404	لینک یافت نشد

GET/panel/api/v1/domains

دامنه‌های لینک اختصاصی

دامنه‌های فعال برای لینک custom (عمومی).

احراز هویت: بدون نیاز به توکن

پاسخ	شرح
200	فهرست

صفحه‌ی اختصاصی

صفحه‌ی عمومی شخصی با فایل‌ها و توضیحات.

GET/panel/api/v1/pages

فهرست صفحات اختصاصی

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پاسخ	شرح
200	فهرست
401	توکن نامعتبر

GET/panel/api/v1/pages/{page_id}

جزئیات صفحه

شامل بلوک‌های فایل و متن.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
page_id	مسیر	integer	بله	شناسه‌ی صفحه

پاسخ	شرح
200	صفحه
404	صفحه یافت نشد

POST/panel/api/v1/pages

ساخت صفحه‌ی اختصاصی

multipart/form-data. blocks_json فهرستی JSON از بلوک‌هاست: {"type":"file","file_id":42,"display_name":"..."} یا {"type":"text","text":"..."} — حداکثر ۱۰ فایل و ۱۰ متن.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

بدنه: multipart/form-data

فیلد	نوع	توضیح
title	string
bio	string
slug	string
theme	string	پیش‌فرض: sky
is_public	string (1 \| 0)
audience	string (public \| specific)
allowed_phones	string	هر شماره در یک خط (برای audience=specific)
contact_phone	string
contact_email	string
logo	string (فایل)
remove_logo	string (1)
blocks_json	string

پاسخ	شرح
200	ساخته شد
400	ورودی نامعتبر
403	آدرس رزرو است
409	آدرس تکراری است

POST/panel/api/v1/pages/{page_id}

ویرایش صفحه

همان فیلدهای ساخت صفحه.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
page_id	مسیر	integer	بله	شناسه‌ی صفحه

بدنه: multipart/form-data

فیلد	نوع	توضیح
title	string
blocks_json	string

پاسخ	شرح
200	ذخیره شد
404	صفحه یافت نشد

POST/panel/api/v1/pages/{page_id}/toggle

فعال/غیرفعال کردن صفحه

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
page_id	مسیر	integer	بله	شناسه‌ی صفحه

پاسخ	شرح
200	انجام شد
404	صفحه یافت نشد

DELETE/panel/api/v1/pages/{page_id}

حذف صفحه

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
page_id	مسیر	integer	بله	شناسه‌ی صفحه

پاسخ	شرح
200	حذف شد
404	صفحه یافت نشد

فضا و پرداخت

قیمت، خرید و تمدید فضای ابری.

GET/panel/api/v1/storage-plans

قیمت و محدوده‌ی خرید فضا

محدوده‌ی مجاز حجم و مدت، وضعیت پلن فعلی، قیمت پیش‌نمایش (با size_bytes و duration_days) و درگاه‌های فعال.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
size_bytes	query	integer	خیر	حجم برای پیش‌نمایش قیمت
duration_days	query	integer	خیر	مدت برای پیش‌نمایش قیمت

پاسخ	شرح
200	اطلاعات

POST/panel/api/v1/orders

خرید یا تمدید فضا

در حالت پرداخت واقعی، gateway_url را در مرورگر باز کنید؛ بعد از بازگشت، وضعیت را با GET /orders/{order_id} بخوانید.

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

بدنه: application/json

فیلد	نوع	توضیح
mode	string (new \| renew)	پیش‌فرض: new
amount	number	پیش‌فرض: 1
unit	string (MB \| GB \| TB)	پیش‌فرض: GB
duration_days	integer
gateway	string

{
  "amount": 10,
  "duration_days": 30,
  "mode": "new",
  "unit": "GB"
}

پاسخ	شرح
200	سفارش ساخته شد
400	ورودی نامعتبر
502	خطای درگاه

GET/panel/api/v1/orders/{order_id}

وضعیت سفارش

احراز هویت: توکن JWT اپ — از «ورود با کد یک‌بارمصرف» (۳۰ روز اعتبار)

پارامتر	محل	نوع	الزامی	توضیح
order_id	مسیر	integer	بله	شناسه‌ی سفارش

پاسخ	شرح
200	سفارش
404	سفارش یافت نشد

همگام‌سازی دسکتاپ

API ابزار همگام‌سازی پوشه‌ی کامپیوتر با نابغه فایل.

GET/panel/api/v1/sync/files

فهرست فایل‌ها برای همگام‌سازی

همه‌ی فایل‌های فعال با هش SHA-256 برای مقایسه‌ی محلی بدون دانلود.

احراز هویت: توکن همگام‌سازی — پنل → همگام‌سازی دسکتاپ (بدون انقضا)

پاسخ	شرح
200	فهرست
401	توکن نامعتبر

POST/panel/api/v1/sync/upload

آپلود/به‌روزرسانی از همگام‌سازی

مسیر پشتیبان (حداکثر ۱۰۰ مگابایت). multipart (فیلد file). فایل هم‌نام موجود نسخه‌دار به‌روز می‌شود؛ اگر محتوا تغییری نکرده باشد unchanged=true برمی‌گردد. اولویت اول: /uploads/authorize با purpose=sync.

احراز هویت: توکن همگام‌سازی — پنل → همگام‌سازی دسکتاپ (بدون انقضا)

بدنه: multipart/form-data

فیلد	نوع	توضیح
file	string (فایل)

پاسخ	شرح
200	ذخیره شد
400	فایل یا فضا نامعتبر

GET/panel/api/v1/sync/files/{file_id}/download

دانلود برای همگام‌سازی

مثل دانلود فایل: 302 به لینک مستقیم سرور انتقال؛ با via=panel یا هنگام قطعی، stream از پنل.

احراز هویت: توکن همگام‌سازی — پنل → همگام‌سازی دسکتاپ (بدون انقضا)

پارامتر	محل	نوع	الزامی	توضیح
file_id	مسیر	integer	بله	شناسه‌ی فایل
via	query	string	خیر	panel = اجبار مسیر پشتیبان

پاسخ	شرح
302	انتقال به لینک دانلود مستقیم
200	محتوای فایل
404	پیدا نشد

DELETE/panel/api/v1/sync/files/{file_id}

حذف از همگام‌سازی

حذف نرم — فایل به سطل بازیافت می‌رود و قابل بازگردانی است.

احراز هویت: توکن همگام‌سازی — پنل → همگام‌سازی دسکتاپ (بدون انقضا)

پارامتر	محل	نوع	الزامی	توضیح
file_id	مسیر	integer	بله	شناسه‌ی فایل

پاسخ	شرح
200	به سطل بازیافت رفت

بکاپ خودکار

آپلود بکاپ از اسکریپت زمان‌بندی‌شده‌ی سرور شما.

POST/panel/api/v1/backup/upload

آپلود بکاپ

مسیر پشتیبان (حداکثر ۱۰۰ مگابایت) برای اسکریپت زمان‌بندی‌شده‌ی سرور شما (multipart، فیلد file). قدیمی‌ترها طبق تعداد نگهداری خودکار پاک می‌شوند. اولویت اول: /uploads/authorize با توکن بکاپ (اسکریپت آماده‌ی پنل خودش همین کار را می‌کند).

احراز هویت: توکن بکاپ خودکار — پنل → بکاپ‌گیری خودکار (بدون انقضا)

بدنه: multipart/form-data

فیلد	نوع	توضیح
file	string (فایل)

پاسخ	شرح
200	ذخیره شد
400	فایل خالی/ارسال‌نشده
401	توکن نامعتبر
502	سرور ذخیره‌سازی در دسترس نیست