RESTful Developer Platform

OnlySub Developer Documentation

Access the full MediaSync AI subtitle engine via high-speed, standard REST endpoints. Ideal for custom media players, bots, and streaming addons.

Interactive Swagger Docs

Base URL

https://onlysub.ir/api/v1

Secured with TLS 1.3 & Gzip

Rate Limits

60 Req/min (Public)

No API key required for public GET

Encoding & Format

UTF-8 Without BOM • SubRip (.srt)

100% compatible with Smart TVs & Players

Quickstart Code Snippet

# واکشی اطلاعات زیرنویس با شناسه فیلم
curl -X GET "https://onlysub.ir/api/v1/movies/interstellar" \
  -H "Accept: application/json"

Available API Endpoints (v1)

GET/api/v1/movies/search

q=Interstellar

Search movies and TV shows by English/Persian title or IMDb ID

Sample JSON Response:

{
  "items": [
    {
      "id": "47f49201-cdda-4a25-932e-f933801c8256",
      "slug": "interstellar",
      "title_en": "Interstellar",
      "title_fa": "میان‌ستاره‌ای",
      "release_year": 2014,
      "imdb_id": "tt0816692",
      "imdb_rating": 8.7
    }
  ],
  "total": 1
}

GET/api/v1/movies/{id_or_slug}

interstellar

Retrieve media metadata, plot summary, and all verified subtitle tracks

Sample JSON Response:

{
  "id": "47f49201-cdda-4a25-932e-f933801c8256",
  "slug": "interstellar",
  "title_en": "Interstellar",
  "title_fa": "میان‌ستاره‌ای",
  "release_year": 2014,
  "imdb_id": "tt0816692",
  "imdb_rating": 8.7,
  "subtitles": [
    {
      "id": "sub_fa_001",
      "language_code": "fa",
      "format": "srt",
      "downloads_count": 842,
      "is_ai_generated": true
    }
  ]
}

GET/api/v1/subtitles/download/{id}

sub_fa_001?format=srt&mode=uncensored

Direct stream download of UTF-8 subtitle file with uncensored/family filtering

Sample JSON Response:

1
00:01:14,200 --> 00:01:17,800
پدرم یک کشاورز بود، مثل بقیه در آن دوران.

2
00:01:18,100 --> 00:01:21,500
اما او هرگز فراموش نکرد که ما کاشف هستیم...

GET/stremio/manifest.json

Official Stremio v3 Subtitle Addon Protocol manifest for automated playback sync

Sample JSON Response:

{
  "id": "org.onlysub.addon",
  "version": "1.0.0",
  "name": "OnlySub AI Subtitles",
  "description": "Multi-language AI cinema subtitles by MediaSync",
  "resources": ["subtitles"],
  "types": ["movie", "series"]
}