دانلودها

ایجاد دانلود با فایل تورنت یا یوزنت

POSThttps://api.parsget.com/api/v1/downloads/upload

OAuth یا Personal API Key

برای ثبت دانلود از فایل تورنت یا یوزنت، فایل .torrent، .nzb یا .xml را در فیلد file با multipart/form-data بفرستید. سقف اندازه فایل ۴۰ MiB است.

مانند POST /downloads، پاسخ 201 و data.kind برابر download یعنی دانلود ثبت شده است. پاسخ 200 و data.kind برابر selection یعنی باید یک گزینه انتخاب کنید. client_reference و webhook_url در هر دو روش رفتار یکسانی دارند.

OAuth Scope: downloads:write

اگر به انتخاب کاربر نیاز باشد، پاسخ شامل data.kind=selection و گزینه‌های قابل انتخاب است.

اگر همان تورنت (با همان info hash) هم‌اکنون برای کاربر دیگری در حال دانلود باشد، دانلود شما به همان دانلود متصل می‌شود: پاسخ یک دانلود عادی است، پیشرفت آن با کمی تأخیر (تا حدود ۱۵ ثانیه) به‌روز می‌شود و هزینه مثل هر دانلود دیگری هنگام تکمیل کسر می‌شود. اگر آن دانلود ناموفق شود، دانلود شما هم با همان خطا ناموفق می‌شود و اعتبار رزروشده آزاد می‌شود. فقط وقتی آن تورنت در حال seed باشد، یا درخواست دیگری برای همان تورنت پس از چند ثانیه هنوز در حال پردازش باشد، پاسخ 409 با error.code برابر resource_conflict برمی‌گردد و هزینه‌ای کسر نمی‌شود؛ کمی بعد دوباره تلاش کنید.

Request body

multipart/form-datarequired

Field	Type	Description
`file`	`string`requiredbinary	فایل .torrent، .nzb یا .xml تا ۴۰ MiB، یا فایل لینک (.dlc، .rsdf، .ccf، .metalink، .meta4، .sfdl) تا ۲ MiB. سرور نوع فایل را تشخیص می‌دهد. فایل لینک دانلود نمی‌شود: لینک‌های داخل آن در یک مرحله انتخاب (kind=selection) برمی‌گردند.
`directory`	`string`optional	مسیر پوشه مقصد در فضای کاربر، مانند Movies.
`client_reference`	`string`optional	برچسب دلخواه برای ارتباط دانلود با داده‌های برنامه شما. چند دانلود می‌توانند برچسب یکسان داشته باشند.
`webhook_url`	`string`optionaluri	آدرس عمومی HTTPS برنامه شما برای دریافت نتیجه دانلود، شامل تکمیل، خطا یا لغو آن. پیش از استفاده، برای Personal API Key یا برنامه OAuth خود webhook secret بسازید.

Response schema

200برای ایجاد دانلود، کاربر باید از فهرست پاسخ، فایل، قسمت یا کیفیت موردنظر را انتخاب کند.

Payloadobject

Field	Type	Description
`kind`	`string` `selection`	—
`selection`	`object`
`id`	`string`	—
`prompt`	`string`	عنوان یا راهنمای مرحله انتخاب برای نمایش به کاربر
`expires_at`	`string`date-time	مهلت انتخاب کاربر. پس از این زمان، شناسه مرحله و گزینه‌های آن معتبر نیستند.
`items`	`object[]`
`id`	`string`	شناسه گزینه در مرحله انتخاب فعلی.
`parent_id`	`string`	شناسه گزینه‌ای که این مورد زیرمجموعه آن است. برای گزینه‌های سطح اول، null است.
`name`	`string`	—
`size_bytes`	`integer`int64 min 0	—
`kind`	`string` `directoryvideoaudioimagedocumentnull`	—
`status`	`string` `nonesubmittedreadynull`	—
`tags`	`Record<string, string>`	—
`thumbnail_url`	`string`uri	—
`selectable`	`boolean`	اگر true باشد، کاربر می‌تواند این گزینه را انتخاب کند.

201دانلود با موفقیت ایجاد شد

Payloadobject

Field	Type	Description
`kind`	`string` `download`	—
`download`	`object`
`id`	`string`	—
`client_reference`	`string`	برچسب دلخواه برای ارتباط دانلود با داده‌های برنامه شما، مثلاً شناسه قسمت یک مجموعه. چند دانلود می‌توانند برچسب یکسان داشته باشند.
`name`	`string`	—
`status`	`string` `queuedprocessingdownloadingfinalizingcompletedblockedfailedcanceled`	وضعیت دانلود. queued یعنی در صف، processing یعنی در حال بررسی و آماده‌سازی دانلود، downloading یعنی دریافت فایل و finalizing یعنی آماده‌سازی نهایی. completed یعنی تکمیل شده، blocked یعنی نیازمند پرداخت، failed یعنی ناموفق و canceled یعنی لغوشده.
`activity`	`string` `seedingwaiting_for_capacitynull`	پس از تکمیل تورنت، ممکن است ارسال فایل به دیگر کاربران تورنت ادامه داشته باشد. در این حالت، activity برابر seeding و status برابر completed است. وقتی همه اکانت‌های سرویس موقتاً مشغول یا در محدودیت هستند، دانلود با status برابر queued و activity برابر waiting_for_capacity منتظر می‌ماند و با آزاد شدن ظرفیت خودکار ادامه پیدا می‌کند؛ اگر در مهلت تلاش مجدد ظرفیتی آزاد نشود، failed می‌شود.
`source`	`object`
`type`	`string` `urltorrentusenet`	—
`hash`	`string`	هش تورنت (فقط برای دانلودهای تورنت مقدار دارد)
`host`	`string`	کد سرویس دانلود؛ برای اطلاعات سرویس آن را با code در GET /services تطبیق دهید.
`file_id`	`string`	شناسه فایل ایجادشده پس از تکمیل موفق دانلود
`mime_type`	`string`	—
`size_bytes`	`integer`int64	—
`progress`	`object`
`percent`	`number`float min 0max 100	درصد پیشرفت دانلود از ۰ تا ۱۰۰.
`bytes_completed`	`integer`int64 min 0	حجم دریافت‌شده بر حسب بایت.
`speed_bytes_per_second`	`number` min 0	سرعت دریافت بر حسب بایت بر ثانیه؛ اگر مشخص نباشد null است.
`eta_seconds`	`number` min 0	زمان تخمینی باقی‌مانده بر حسب ثانیه؛ اگر مشخص نباشد null است.
`can_cancel`	`boolean`	اگر true باشد، می‌توانید دانلود را لغو کنید. دکمه لغو را بر اساس این مقدار نمایش دهید.
`can_retry`	`boolean`	اگر true باشد، می‌توانید دانلود را دوباره شروع کنید. دکمه تلاش مجدد را بر اساس این مقدار نمایش دهید.
`error`	`object \| null`
`code`	`string` `source_unavailabledownload_expiredquota_exceededdownload_failed`	—
`message`	`string`	—
`created_at`	`string`date-time	—
`updated_at`	`string`date-time	—
`completed_at`	`string`date-time	—
`attempt`	`integer` min 1	شماره تلاش دانلود، از ۱. با شروع موفق یک تلاش جدید از طریق endpoint retry افزایش می‌یابد.

پاسخ‌های خطاساختار استاندارد error

Example

{
  "data": {
    "kind": "selection",
    "selection": {
      "id": "dls_01M1BDA500E8G2K4N6Q7R9TVWX",
      "prompt": "Choose a file",
      "expires_at": "2026-08-31T20:00:00.000000Z",
      "items": [
        {
          "id": "dli_01M1BDA500F9H3M5P7S8T2VWXY",
          "parent_id": null,
          "name": "big-buck-bunny.mp4",
          "size_bytes": 734003200,
          "kind": "video",
          "status": "ready",
          "tags": {
            "season": "1",
            "episode": "1"
          },
          "thumbnail_url": "https://images.parsget.com/selections/big-buck-bunny.webp",
          "selectable": true
        }
      ]
    }
  }
}