مستندات API جستجوی زیرنویس (نسخه بتا)

نمای کلی

API جستجوی زیرنویس به کاربران امکان می‌دهد برای زیرنویس‌های فیلم یا سریال بر اساس معیارهای مختلف مانند نام فیلم، نام فایل، شناسه‌های خاص (IMDB، TMDB، SubDL)، شماره فصل و قسمت، نوع (فیلم یا سریال)، سال انتشار و زبان‌ها جستجو کنند.

نقطه پایانی: https://api.subdl.com/api/v1/subtitles روش: GET

پارامترهای درخواست

یکی از این متغیرها را به عنوان URL GET ارسال کنید

• api_key (الزامی): کلید API از حساب subdl
• client (اختیاری): برنامه‌ای که از کلید استفاده می‌کند؛ یکی از bazarr، stremio، kodi، subdl_player، custom_integration یا other.
• film_name (اختیاری): جستجوی متنی بر اساس نام فیلم.
• file_name (اختیاری): جستجو بر اساس نام فایل.
• sd_id (اختیاری): جستجو بر اساس شناسه SubDL.
• imdb_id (اختیاری): جستجو بر اساس شناسه IMDb.
• tmdb_id (اختیاری): جستجو بر اساس شناسه TMDB.
• season_number (اختیاری): شماره فصل خاص برای سریال‌ها.
• episode_number (اختیاری): شماره قسمت خاص برای سریال‌ها.
• type (اختیاری): نوع محتوا، یا movie یا tv.
• year (اختیاری): سال انتشار فیلم یا سریال.
• languages (اختیاری): کدهای زبان جدا شده با کاما برای زبان‌های زیرنویس. لیست زبان‌های پشتیبانی شده
• subs_per_page (اختیاری): محدودیت زیرنویس‌هایی که در نتایج نمایش داده می‌شوند، پیش‌فرض 10 است (حداکثر می‌تواند 30 باشد)
• comment (اختیاری): comment=1 را ارسال کنید تا نظر نویسنده در مورد زیرنویس را دریافت کنید
• releases (اختیاری): releases=1 را ارسال کنید تا لیست انتشارها را برای زیرنویس دریافت کنید
• hi (اختیاری): hi=1 را ارسال کنید تا مشخص شود آیا زیرنویس برای ناشنوایان است
• full_season (اختیاری): full_season=1 را ارسال کنید تا تمام زیرنویس‌های فصل کامل را دریافت کنید

پاسخ موفق

یک پاسخ موفق یک شیء JSON با فیلدهای زیر را برمی‌گرداند:

• status: یک مقدار بولی که نشان‌دهنده وضعیت موفقیت است (true).
• results: آرایه‌ای از فیلم‌ها یا سریال‌های مطابق با معیارهای جستجو.
• subtitles: آرایه‌ای از زیرنویس‌های مطابق با معیارهای جستجو برای اولین فیلم/سریال در نتایج.

پاسخ خطا

پاسخ خطا به صورت یک شیء JSON با فیلدهای زیر برگردانده می‌شود:

• status: یک مقدار بولی که نشان‌دهنده وضعیت موفقیت است (false).
• error: پیام خطا که دلیل شکست را نشان می‌دهد.

مثال لینک دانلود

لینک زیرنویس را به نقطه پایانی dl.subdl.com مانند این مثال اضافه کنید:

https://dl.subdl.com/subtitle/3197651-3213944.zip

دانلود فایل خام srt به زودی…

مثال استفاده

درخواست

{
  "query": {
    "api_key": "abcdefghisubdl",
    "film_name": "Inception",
    "type": "movie",
    "languages": "EN,FR"
  }
}

بدنه پاسخ

{
  "status": true,
  "results": [
    {
      "imdb_id": "tt1375666",
      "tmdb_id": 27205,
      "type": "movie",
      "name": "Inception",
      "sd_id": 123456,
      "first_air_date": null,
      "year": 2010
    }
  ],
  "subtitles": [
    {
      // جزئیات زیرنویس
    }
  ]
}

نکات

• محدودیت نرخ API اعمال می‌شود؛ اطمینان حاصل کنید که تعداد درخواست‌ها را مطابق با مجوز کلید API خود مدیریت می‌کنید.
• جستجو بهینه‌سازی شده است تا ابتدا به دنبال تطابق‌های دقیق در پایگاه داده بگردد و سپس در صورت لزوم با معیارهای گسترده‌تر ادامه دهد.
• کدهای زبان باید از فرمت خاص ارائه شده در مستندات API پیروی کنند تا فیلتر کردن دقیق زیرنویس‌ها تضمین شود.

این API ابزاری قدرتمند برای توسعه‌دهندگان فراهم می‌کند تا عملکرد جستجوی زیرنویس را در برنامه‌های خود ادغام کنند و گزینه‌های فیلتر گسترده‌ای را برای پاسخگویی به طیف وسیعی از ترجیحات کاربر ارائه می‌دهد.

مثال درخواست CURL

curl -X GET "https://api.subdl.com/api/v1/subtitles?api_key=example-api-key&film_name=Inception&type=movie&languages=EN"

مثال کد JavaScript برای درخواست

fetch(
  "https://api.subdl.com/api/v1/subtitles?api_key=example-api-key&film_name=Inception&type=movie&languages=fa",
  {
    method: "GET",
    headers: {
      Accept: "application/json",
    },
  }
)
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("خطا:", error));