Ejemplos en Python

Ejemplos completos en Python para usar la API de SubX.

Instalación

pip install requests python-dotenv

Configuración Básica

import os
import requests
from dotenv import load_dotenv

# Cargar variables de entorno
load_dotenv()

API_KEY = os.getenv('SUBX_API_KEY')
BASE_URL = "https://subx-api.duckdns.org"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

Ejemplos Completos

1. Flujo de Búsqueda y Descarga

import requests
import os
from pathlib import Path

class SubXClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://subx-api.duckdns.org"
        self.headers = {"Authorization": f"Bearer {api_key}"}

    def search(self, **kwargs):
        """Buscar subtítulos."""
        response = requests.get(
            f"{self.base_url}/api/subtitles/search",
            headers=self.headers,
            params=kwargs
        )
        response.raise_for_status()
        return response.json()

    def get_subtitle(self, subtitle_id):
        """Obtener detalles del subtítulo."""
        response = requests.get(
            f"{self.base_url}/api/subtitles/{subtitle_id}",
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def download(self, subtitle_id, output_path):
        """Descargar archivo de subtítulos."""
        response = requests.get(
            f"{self.base_url}/api/subtitles/{subtitle_id}/download",
            headers=self.headers
        )
        response.raise_for_status()

        # Guardar archivo
        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
        with open(output_path, "wb") as f:
            f.write(response.content)

        return output_path

# Uso
client = SubXClient(os.getenv('SUBX_API_KEY'))

# Buscar
results = client.search(title="Dexter", limit=10)
print(f"Encontrados {results['total']} subtítulos")

# Descargar primer resultado
if results['items']:
    subtitle = results['items'][0]
    output = client.download(subtitle['id'], f"subtitles/{subtitle['title']}.srt")
    print(f"Descargado: {output}")

2. Búsqueda Avanzada con Filtros

def search_series_episode(client, imdb_id, season, episode):
    """Buscar un episodio específico de TV."""
    results = client.search(
        imdb_id=imdb_id,
        video_type="episode",
        limit=200
    )

    # Filtrar por temporada y episodio
    matches = [
        sub for sub in results['items']
        if sub.get('season') == season and sub.get('episode') == episode
    ]

    return matches

# Encontrar Dexter S01E01
episodes = search_series_episode(client, "tt0773262", season=1, episode=1)
print(f"Encontrados {len(episodes)} subtítulos coincidentes")

3. Descarga en Lote con Progreso

from concurrent.futures import ThreadPoolExecutor, as_completed
from tqdm import tqdm

def batch_download(client, subtitle_ids, output_dir="subtitles", max_workers=3):
    """Descargar múltiples subtítulos de forma concurrente con barra de progreso."""
    os.makedirs(output_dir, exist_ok=True)

    def download_one(sub_id):
        try:
            # Obtener detalles para nombre de archivo
            details = client.get_subtitle(sub_id)
            filename = f"{details['title']}_S{details.get('season', 0):02d}E{details.get('episode', 0):02d}.srt"
            output = os.path.join(output_dir, filename)

            client.download(sub_id, output)
            return {'id': sub_id, 'success': True, 'file': filename}
        except Exception as e:
            return {'id': sub_id, 'success': False, 'error': str(e)}

    results = []
    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = {executor.submit(download_one, sid): sid for sid in subtitle_ids}

        for future in tqdm(as_completed(futures), total=len(subtitle_ids), desc="Descargando"):
            results.append(future.result())

    success_count = sum(1 for r in results if r['success'])
    print(f"\nCompletado: {success_count}/{len(subtitle_ids)} exitosos")

    return results

Ver la Guía de Inicio Rápido para más ejemplos básicos.