فایل‌ها

دریافت جزئیات فایل یا پوشه

GEThttps://api.parsget.com/api/v1/files/{file}

OAuth یا Personal API Key

مشخصات فایل یا پوشه را دریافت کنید. برای دریافت پوستر ویدیو، include_poster=true و برای جزئیات صوتی و تصویری و زیرنویس‌های داخل فایل، include_media=true بفرستید. این اطلاعات به‌صورت پیش‌فرض در پاسخ نمی‌آیند. برای خواندن دوباره، ETag پاسخ قبلی را در If-None-Match بفرستید؛ پاسخ 304 یعنی تغییری نکرده است.

OAuth Scope: files:read

Parameters

Field	Type	Description
`file`	`string · path`required	شناسه یکتای فایل یا پوشه
`include_state`	`boolean · query`optional default `false`	برای دریافت داده‌هایی که برنامه شما برای این فایل یا پوشه ذخیره کرده، مقدار true بفرستید. این داده‌ها در app_state می‌آیند. به توکن OAuth با دسترسی‌های files:read و storage:read نیاز دارید. پیش‌فرض false است و این فیلد در پاسخ نمی‌آید.
`include_poster`	`boolean · query`optional default `false`	برای دریافت آدرس و مشخصات پوستر ویدیو، مقدار true بفرستید. پیش‌فرض false است و فیلد poster در پاسخ نمی‌آید. اگر پوستر را درخواست کنید اما موجود نباشد، مقدار آن null است.
`include_media`	`boolean · query`optional default `false`	برای دریافت مشخصات صوتی و تصویری ویدیو در فیلد media، مقدار true بفرستید. پیش‌فرض false است و این فیلد در پاسخ نمی‌آید.
`If-None-Match`	`string · header`optional	ETag پاسخ قبلی را برای همین درخواست، با همان پارامترها، بفرستید. اگر چیزی تغییر نکرده باشد، پاسخ 304 بدون بدنه است و نسخه ذخیره‌شده شما هنوز معتبر است.

Response schema

200مشخصات فایل یا پوشه

Payloadobject

Field	Type	Description
`id`	`string`	—
`parent_id`	`string`	شناسه پوشه‌ای که فایل یا پوشه فعلی داخل آن قرار دارد. برای مواردی که داخل هیچ پوشه‌ای نیستند، null است.
`download_id`	`string`	شناسه دانلود مرتبط با فایل یا پوشه؛ اگر دانلود مرتبطی نداشته باشد null است.
`name`	`string`	—
`type`	`string` `filefolder`	—
`kind`	`string` `foldervideoaudioimagedocumentarchivesubtitleother`	—
`media`	`object \| null`	مشخصات صوتی و تصویری ویدیو؛ فقط با include_media=true در پاسخ می‌آید و برای فایل‌های غیر ویدیویی null است. GET /files خلاصه مشخصات و GET /files/{file} جزئیات کامل را برمی‌گرداند.
`status`	`string` `pendingreadyunavailable`	وضعیت آماده‌سازی مشخصات رسانه: pending یعنی در انتظار آماده‌سازی، ready یعنی آماده و unavailable یعنی در دسترس نیست. وضعیت دانلود را جداگانه از status دانلود بخوانید.
`title`	`string`	عنوان ثبت‌شده در متادیتای فایل رسانه.
`description`	`string`	—
`creation_time`	`string`	زمان ایجاد رسانه که در متادیتای فایل ثبت شده است.
`format_names`	`string[]`	—
`duration_ms`	`integer`int64	مدت پخش بر حسب میلی‌ثانیه.
`bitrate`	`integer`int64	—
`width`	`integer`	—
`height`	`integer`	—
`chapters`	`object[]`
`start_ms`	`integer`int64 min 0	—
`end_ms`	`integer`int64 min 1	—
`title`	`string`	—
`video_streams`	`object[]`
`index`	`integer`	—
`codec`	`string`	—
`codec_tag`	`string`	—
`profile`	`string`	—
`level`	`integer`	—
`width`	`integer`	—
`height`	`integer`	—
`display_aspect_ratio`	`string`	—
`sample_aspect_ratio`	`string`	—
`pixel_format`	`string`	—
`frame_rate`	`string`	—
`bitrate`	`integer`	—
`color_range`	`string`	—
`color_space`	`string`	—
`color_transfer`	`string`	—
`color_primaries`	`string`	—
`hdr`	`boolean`	اگر true باشد، ویدیو HDR است.
`rotation`	`integer`	—
`default`	`boolean`	—
`audio_streams`	`object[]`
`index`	`integer`	—
`codec`	`string`	—
`profile`	`string`	—
`channels`	`integer`	—
`channel_layout`	`string`	—
`sample_rate`	`integer`	—
`bitrate`	`integer`	—
`language`	`string`	—
`title`	`string`	—
`default`	`boolean`	—
`original`	`boolean`	—
`commentary`	`boolean`	—
`hearing_impaired`	`boolean`	—
`visual_impaired`	`boolean`	—
`subtitle_streams`	`object[]`	مشخصات زیرنویس‌های داخل فایل ویدیو.
`index`	`integer`	—
`codec`	`string`	—
`language`	`string`	—
`title`	`string`	—
`default`	`boolean`	—
`forced`	`boolean`	—
`original`	`boolean`	—
`commentary`	`boolean`	—
`hearing_impaired`	`boolean`	—
`poster`	`object \| null`	آدرس و مشخصات پوستر برای نمایش پیش‌نمایش ویدیو؛ فقط با include_poster=true در پاسخ می‌آید. اگر پوستر در دسترس نباشد، مقدار آن null است.
`url`	`string`uri	—
`expires_at`	`null`	پوستر انقضای زمانی ندارد
`width`	`integer` max 640	—
`height`	`integer`	—
`mime_type`	`string` `image/webp`	—
`dominant_color`	`string`	رنگ غالب پوستر به‌صورت کد Hex، برای مثال برای رنگ پس‌زمینه پیش‌نمایش.
`size_bytes`	`integer`int64 min 0	—
`mime_type`	`string`	—
`locked`	`boolean`	اگر true باشد، فایل قفل است و نمی‌توانید برای آن لینک دانلود یا پخش بگیرید.
`expires_at`	`string`date-time	زمان انقضای فایل در حساب؛ با زمان انقضای لینک دانلود متفاوت است.
`created_at`	`string`date-time	—
`updated_at`	`string`date-time	—
`app_state`	`object \| null`	داده‌هایی که برنامه شما برای این کاربر و فایل یا پوشه ذخیره کرده است، مانند موقعیت پخش ویدیو. فقط با include_state=true در پاسخ می‌آید. اگر هنوز داده‌ای ذخیره نکرده باشید، مقدار آن null است.
`value`	`Record<string, any>`	داده‌های دلخواه برنامه در قالب یک شیء JSON با حداکثر حجم ۶۴ KiB. فیلدهای داخل این شیء را خودتان تعیین می‌کنید.
`version`	`integer` min 1	—
`etag`	`string`	برای ارسال If-Match، این مقدار را کامل و همراه با علامت نقل‌قول کپی کنید. ETag را از روی version نسازید.
`created_at`	`string`date-time	—
`updated_at`	`string`date-time	—

304تغییری نکرده است؛ بدنه ندارد. از پاسخ ذخیره‌شده خود استفاده کنید.

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

Example

{
  "data": {
    "id": "01M1BDK9Z0C6E9G2K5N7Q3R4TX",
    "parent_id": null,
    "download_id": "01M1BDA500B4A6D9K3N5R7T8VC",
    "name": "big-buck-bunny.mp4",
    "type": "file",
    "kind": "video",
    "size_bytes": 1073741824,
    "mime_type": "video/mp4",
    "locked": false,
    "expires_at": "2026-09-30T08:05:00.000000Z",
    "created_at": "2026-08-31T08:05:00.000000Z",
    "updated_at": "2026-08-31T08:05:00.000000Z",
    "media": {
      "status": "ready",
      "title": "Big Buck Bunny",
      "description": null,
      "creation_time": null,
      "format_names": [
        "mov",
        "mp4",
        "m4a",
        "3gp",
        "3g2",
        "mj2"
      ],
      "duration_ms": 596000,
      "bitrate": 14400000,
      "width": 1920,
      "height": 1080,
      "chapters": [],
      "video_streams": [],
      "audio_streams": [],
      "subtitle_streams": []
    },
    "poster": {
      "url": "https://api.parsget.com/images/posters/01K3W2G9K3Z6J7K8N9P0Q1R2S3/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb/poster-lg.webp",
      "expires_at": null,
      "width": 640,
      "height": 360,
      "mime_type": "image/webp",
      "dominant_color": "#6b7280"
    }
  }
}