Get Subtitle¶

Retrieve detailed information about a specific subtitle by its ID.

Endpoint¶

GET /api/subtitles/{subtitle_id}

Authentication¶

✅ Authentication required - Include your API key in the Authorization header.

Description¶

This endpoint retrieves complete information about a single subtitle using its unique UUID. Use this when you already have a subtitle ID from a search result and want to get its full details.

Path Parameters¶

Parameter	Type	Required	Description
`subtitle_id`	string (UUID)	Yes	Unique subtitle identifier

Request Examples¶

=== "cURL"

curl -X GET "https://subx-api.duckdns.org/api/subtitles/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer {YOUR_API_KEY_HERE}"

Python

import requests

subtitle_id = "550e8400-e29b-41d4-a716-446655440000"
headers = {"Authorization": "Bearer {YOUR_API_KEY_HERE}"}

response = requests.get(
    f"https://subx-api.duckdns.org/api/subtitles/{subtitle_id}",
    headers=headers
)

subtitle = response.json()
print(f"Title: {subtitle['title']}")
print(f"Downloads: {subtitle['downloads']}")

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    apiKey := "{YOUR_API_KEY_HERE}"
    subtitleID := "550e8400-e29b-41d4-a716-446655440000"
    url := fmt.Sprintf("https://subx-api.duckdns.org/api/subtitles/%s", subtitleID)

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var subtitle map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&subtitle)

    fmt.Printf("Title: %v\n", subtitle["title"])
    fmt.Printf("Downloads: %v\n", subtitle["downloads"])
}

C# / .NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;

var subtitleId = "550e8400-e29b-41d4-a716-446655440000";
var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "{YOUR_API_KEY_HERE}");

var url = $"https://subx-api.duckdns.org/api/subtitles/{subtitleId}";
var response = await client.GetAsync(url);
var json = await response.Content.ReadAsStringAsync();

var subtitle = JsonSerializer.Deserialize<JsonElement>(json);
Console.WriteLine($"Title: {subtitle.GetProperty("title")}");
Console.WriteLine($"Downloads: {subtitle.GetProperty("downloads")}");

JavaScript

const subtitleId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://subx-api.duckdns.org/api/subtitles/${subtitleId}`,
  {
    headers: {
      'Authorization': 'Bearer {YOUR_API_KEY_HERE}'
    }
  }
);

const subtitle = await response.json();
console.log(`Title: ${subtitle.title}`);
console.log(`Downloads: ${subtitle.downloads}`);

Response¶

Success Response (200 OK)¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "video_type": "episode",
  "title": "Dexter",
  "season": 1,
  "episode": 1,
  "year": 2006,
  "imdb_id": "tt0773262",
  "description": "Dexter S01E01 - Dexter\nRelease: HDTV.XviD-LOL\nBlu-ray rip version also available",
  "uploader_name": "user123",
  "posted_at": "2024-01-15T10:30:00Z",
  "downloads": 1250
}

Response Fields¶

Field	Type	Description
`id`	string (UUID)	Unique subtitle identifier
`video_type`	string	Type: `movie` or `episode`
`title`	string	Title of the movie/show
`season`	integer \| null	Season number (for episodes)
`episode`	integer \| null	Episode number (for episodes)
`year`	integer \| null	Movie release year or parent show's premiere year
`imdb_id`	string \| null	IMDb identifier (e.g., `tt0773262`)
`description`	string \| null	Subtitle description/release info
`uploader_name`	string \| null	Original uploader username
`posted_at`	string	ISO 8601 timestamp
`downloads`	integer	Total download count (source + API)

Status Codes¶

Code	Description
200	Success - Subtitle found
401	Unauthorized - Invalid or missing API key
404	Not Found - Subtitle doesn't exist or is inactive
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Responses¶

404 Not Found¶

{
  "detail": "Subtitle not found"
}

This error occurs when: - The subtitle ID doesn't exist in the database - The subtitle exists but has been deactivated (is_active=false) - The ID format is invalid (not a valid UUID)

401 Unauthorized¶

{
  "detail": "Invalid authentication credentials"
}

Use Cases¶

1. Get Subtitle Details After Search¶

import requests

def search_and_get_details(title):
    """Search for subtitles and get details of first result."""
    headers = {"Authorization": "Bearer {YOUR_API_KEY_HERE}"}

    # Search
    search_response = requests.get(
        "https://subx-api.duckdns.org/api/subtitles/search",
        headers=headers,
        params={"title": title, "limit": 1}
    )

    results = search_response.json()
    if not results['items']:
        print(f"No subtitles found for '{title}'")
        return None

    # Get detailed info
    subtitle_id = results['items'][0]['id']
    detail_response = requests.get(
        f"https://subx-api.duckdns.org/api/subtitles/{subtitle_id}",
        headers=headers
    )

    return detail_response.json()

# Usage
subtitle = search_and_get_details("Breaking Bad")
if subtitle:
    print(f"Title: {subtitle['title']}")
    print(f"Description: {subtitle['description']}")

2. Validate Subtitle Exists Before Download¶

import requests

def download_if_exists(subtitle_id):
    """Check if subtitle exists before attempting download."""
    headers = {"Authorization": "Bearer {YOUR_API_KEY_HERE}"}

    # First, verify subtitle exists
    try:
        response = requests.get(
            f"https://subx-api.duckdns.org/api/subtitles/{subtitle_id}",
            headers=headers
        )
        response.raise_for_status()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 404:
            print("Subtitle not found")
            return False
        raise

    # Subtitle exists, proceed with download
    download_response = requests.get(
        f"https://subx-api.duckdns.org/api/subtitles/{subtitle_id}/download",
        headers=headers
    )

    with open("subtitle.srt", "wb") as f:
        f.write(download_response.content)

    return True

3. Batch Retrieve Multiple Subtitles¶

import requests
from concurrent.futures import ThreadPoolExecutor

def get_subtitle_details(subtitle_id, headers):
    """Get details for a single subtitle."""
    response = requests.get(
        f"https://subx-api.duckdns.org/api/subtitles/{subtitle_id}",
        headers=headers
    )
    if response.status_code == 200:
        return response.json()
    return None

def get_multiple_subtitles(subtitle_ids):
    """Fetch details for multiple subtitles concurrently."""
    headers = {"Authorization": "Bearer {YOUR_API_KEY_HERE}"}

    with ThreadPoolExecutor(max_workers=5) as executor:
        futures = [
            executor.submit(get_subtitle_details, sub_id, headers)
            for sub_id in subtitle_ids
        ]

        results = [f.result() for f in futures]

    # Filter out None values (failed requests)
    return [r for r in results if r is not None]

# Usage
ids = [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e9500-f39c-52e5-b827-557766551111",
    "770fa611-g40d-63f6-c938-668877662222"
]

subtitles = get_multiple_subtitles(ids)
print(f"Retrieved {len(subtitles)} subtitles")

4. Display Subtitle Information¶

import requests
from datetime import datetime

def display_subtitle_info(subtitle_id):
    """Fetch and display formatted subtitle information."""
    headers = {"Authorization": "Bearer {YOUR_API_KEY_HERE}"}

    response = requests.get(
        f"https://subx-api.duckdns.org/api/subtitles/{subtitle_id}",
        headers=headers
    )

    if response.status_code != 200:
        print(f"Error: {response.status_code}")
        return

    sub = response.json()

    print("=" * 60)
    print(f"Title: {sub['title']}")

    if sub['video_type'] == 'episode':
        print(f"Type: TV Episode (S{sub['season']:02d}E{sub['episode']:02d})")
    else:
        print(f"Type: Movie")

    if sub.get('imdb_id'):
        print(f"IMDb: https://www.imdb.com/title/{sub['imdb_id']}/")

    print(f"Uploader: {sub.get('uploader_name', 'Unknown')}")
    print(f"Downloads: {sub['downloads']}")

    posted = datetime.fromisoformat(sub['posted_at'].replace('Z', '+00:00'))
    print(f"Posted: {posted.strftime('%Y-%m-%d %H:%M UTC')}")

    if sub.get('description'):
        print(f"\nDescription:\n{sub['description']}")

    print("=" * 60)

# Usage
display_subtitle_info("550e8400-e29b-41d4-a716-446655440000")

Notes¶

This endpoint returns a single subtitle object (not wrapped in items array like search)
Inactive subtitles (is_active=false) return 404 errors
The downloads field combines both source downloads and API downloads
The id field in the response is the UUID (same as subtitle_id parameter)
For episodes, prefer using the IMDb ID from the response (it may be episode-specific)

Relationship to Other Endpoints¶

graph LR
    A[Search] --> B[Get Subtitle]
    B --> C[Download]
    A --> C

Search → Get Subtitle: Use search to find IDs, then get details
Get Subtitle → Download: Verify subtitle exists before downloading
Search → Download: Can skip "Get Subtitle" if search provides enough info

Next Steps¶

Download Subtitle - Download the actual subtitle file
Search Subtitles - Find subtitles to get IDs from