Legendas são uma parte indispensável da experiência de mídia moderna. Elas superam barreiras linguísticas, aumentam a acessibilidade para deficientes auditivos e ajudam estudantes de idiomas em todo o mundo. No coração da acessibilidade de legendas está o OpenSubtitles, um dos maiores e mais populares repositórios online de arquivos de legendas. Mas o OpenSubtitles é mais do que apenas um site; ele oferece uma poderosa API REST que permite que desenvolvedores integrem seu vasto banco de dados de legendas diretamente em suas aplicações.
Se você está construindo um reprodutor de mídia, um sistema de gerenciamento de conteúdo, uma ferramenta de aprendizado de idiomas ou qualquer aplicação que possa se beneficiar da integração de legendas, a API do OpenSubtitles fornece as ferramentas necessárias. Este guia abrangente irá guiá-lo por tudo que você precisa saber para utilizar efetivamente a API do OpenSubtitles, desde a configuração inicial e autenticação até a busca, download, tradução de legendas e adesão às melhores práticas.
Quer uma plataforma integrada e Tudo-em-Um para sua equipe de desenvolvimento trabalhar em conjunto com máxima produtividade?
O Apidog atende todas as suas exigências e substitui o Postman a um preço muito mais acessível!
O que é a API do OpenSubtitles?
A API do OpenSubtitles é um conjunto de interfaces de programação que permite que desenvolvedores interajam programaticamente com o banco de dados do OpenSubtitles. Em vez de buscar e baixar legendas manualmente no site, as aplicações podem usar a API para realizar essas ações automaticamente. Isso abre um mundo de possibilidades para criar experiências de usuário ricas e sem costura.
Principais Capacidades:
Buscar: Encontre legendas com base em vários critérios, como título de filme/série, ID do IMDB, ID do TMDB, hash do arquivo, idioma e mais. Baixar: Recupere arquivos de legendas específicos identificados através de resultados de busca. Tradução AI: Aproveite a inteligência artificial para traduzir legendas existentes para diferentes idiomas. Recuperação de Informações: Acesse metadados sobre legendas e mídia.
Começando: Seus Primeiros Passos
Antes de poder fazer chamadas para a API, existem alguns pré-requisitos e conceitos fundamentais para entender.
1. Endpoint da API:
Todas as interações com a API REST do OpenSubtitles ocorrem através de uma única URL base:
https://api.opensubtitles.com/api/v1
Todos os endpoints específicos (como busca ou download) são anexados a essa URL base.
2. Registro e Chave da API:
Acessar a API requer autenticação. O método principal envolve usar uma Chave da API.
Registrar: Você precisa primeiro de uma conta no OpenSubtitles. Se você não tem uma, registre-se no site deles. Obter Chave da API: Uma vez registrado, você precisará gerar uma Chave da API. Isso é normalmente feito através do seu perfil de usuário ou uma seção dedicada para desenvolvedores no site do OpenSubtitles. Mantenha sua Chave da API segura, pois ela identifica as requisições da sua aplicação.
3. Autenticação:
A API suporta dois métodos principais de autenticação:
Chave da API: O método mais simples. Inclua sua Chave da API no cabeçalho Api-Key de cada requisição. Api-Key: SUA_CHAVE_API Token JWT: Para potencialmente acessar mais recursos específicos para o usuário ou diferentes limites de taxa (dependendo do design da API), você pode fazer login via o endpoint /login (coberto mais adiante) para obter um Token Web JSON (JWT). Esse token é então incluído no cabeçalho Authorization como um token Bearer. Authorization: Bearer SEU_TOKEN_JWT
Você ainda geralmente precisa fornecer o cabeçalho Api-Key mesmo ao usar um token JWT para a identificação da aplicação.
4. Cabeçalhos Essenciais:
Além dos cabeçalhos de autenticação, cada requisição da API deve incluir:
Content-Type: Para requisições com um corpo (como requisições POST), isso deve ser tipicamente application/json. Content-Type: application/json **User-Agent:** Isso é crucial. A API requer uma string User-Agent descritiva que identifique sua aplicação. User-Agents vagos ou padrão (como python-requests) podem ser bloqueados. Um bom formato é SeuNomeApp v1.0. User-Agent: MeuAppDeLegendas v1.2.3
5. Limitação de Taxa:
Como a maioria das APIs públicas, o OpenSubtitles impõe limites de taxa para garantir um uso justo e a estabilidade do servidor. Exceder esses limites resultará em respostas de erro (geralmente 429 Muitas Requisições). Preste atenção aos seguintes cabeçalhos de resposta para gerenciar sua taxa de requisições:
X-RateLimit-Limit: O número máximo de requisições permitidas na janela atual. X-RateLimit-Remaining: O número de requisições restantes na janela atual. X-RateLimit-Reset: O timestamp (geralmente tempo Unix epoch) quando a janela de limite de taxa se reinicia. Retry-After: Se você receber um erro 429, esse cabeçalho indica quantos segundos você deve esperar antes de tentar novamente.
Implementar lógica na sua aplicação para respeitar esses cabeçalhos é essencial para uma operação confiável.
Mergulho Profundo em Autenticação: O Endpoint /login
Enquanto usar apenas a Chave da API é geralmente suficiente, o endpoint /login permite que sua aplicação autentique como um usuário específico do OpenSubtitles, obtendo um JWT.
Endpoint: POST /login
Propósito: Trocar credenciais de usuário (nome de usuário/senha) por um token de autenticação JWT.
Corpo da Requisição:
{
"username": "seu_nome_de_usuario_opensubtitles",
"password": "sua_senha_opensubtitles"
}
Cabeçalhos:
Content-Type: application/jsonAccept: application/jsonApi-Key: SUA_CHAVE_APIUser-Agent: SeuNomeApp v1.0
Resposta Succesful (Exemplo):
{
"user": {
"allowed_downloads": 100,
"level": "Leech de Legendas",
"user_id": 123456,
"ext_installed": false,
"vip": false
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Este é o JWT
"status": 200
}
Usando o JWT:
Uma vez obtido, inclua este valor token no cabeçalho Authorization para requisições subsequentes:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Usar JWT pode conceder acesso a cotas de download específicas para o usuário ou outros recursos ligados ao nível da conta do usuário ou status VIP. Lembre-se de que os JWTs normalmente têm um tempo de expiração, então você pode precisar reautenticar periodicamente.
Funcionalidade Principal: Buscando Legendas (/subtitles)
Este é talvez o endpoint mais utilizado. Ele permite que você consulte o vasto banco de dados do OpenSubtitles.
Endpoint: GET /subtitles
Propósito: Encontrar legendas com base em vários critérios de busca.
Autenticação: Requer cabeçalho Api-Key (e opcionalmente Authorization: Bearer <token>).
Principais Parâmetros de Consulta:
O poder da busca reside em seus parâmetros de consulta flexíveis. Você pode combiná-los conforme necessário:
query=<string>: Buscar por título de filme ou episódio (ex: query=Matrix, query=Game of Thrones S01E01). imdb_id=<string>: Buscar usando o ID do IMDb (ex: imdb_id=tt0133093). Isso é frequentemente mais preciso que query. tmdb_id=<integer>: Buscar usando o ID do The Movie Database (TMDb) (ex: tmdb_id=603). Também muito preciso. parent_tmdb_id=<integer>: Para buscar episódios, use o ID do TMDb do show (ex: parent_tmdb_id=1399 para Game of Thrones). season_number=<integer>: Combine com parent_tmdb_id (ou imdb_id do show) para encontrar legendas para uma temporada específica. episode_number=<integer>: Combine com parent_tmdb_id (ou imdb_id do show) e season_number para um episódio específico. languages=<string>: Filtrar por códigos de idioma (separados por vírgulas, ex: languages=en,es, languages=fr). Use códigos ISO 639-2B (como eng, spa, fre). moviehash=<string>: Buscar usando um hash único calculado a partir do arquivo de vídeo. Isso fornece a correspondência mais precisa se você tiver o arquivo de vídeo em si. Calcular esse hash geralmente requer bibliotecas ou ferramentas específicas. type=<string>: Filtrar por tipo (movie ou episode). hearing_impaired=<include|exclude|only>: Filtrar para legendas projetadas para deficientes auditivos. machine_translated=<include|exclude|only>: Filtrar com base em se as legendas foram traduzidas por máquina. ai_translated=<include|exclude|only>: Filtrar com base em se as legendas foram traduzidas usando o recurso de IA da API. order_by=<field>: Ordenar resultados (ex: order_by=download_count). order_direction=<asc|desc>: Especificar direção da ordenação.
Exemplo de Requisição de Busca (Encontrando legendas em inglês para "A Origem" via ID do TMDb):
GET /api/v1/subtitles?tmdb_id=27205&languages=en HTTP/1.1
Host: api.opensubtitles.com
Api-Key: SUA_CHAVE_API
User-Agent: MeuAppDeLegendas v1.0
Accept: application/json
Interpretando Resultados da Busca:
A resposta é um objeto JSON contendo um array data. Cada elemento no array representa uma correspondência de legenda.
{
"total_pages": 10,
"total_count": 195,
"per_page": 20,
"page": 1,
"data": [
{
"id": "1234567", // ID da legenda (útil mas não para download)
"type": "subtitles",
"attributes": {
"subtitle_id": "1234567", // ID legado
"language": "en",
"download_count": 500000,
"new_download_count": 150000,
"hearing_impaired": false,
"hd": true,
"format": "srt",
"fps": 23.976,
"votes": 120,
"points": 10,
"ratings": 8.5,
"from_trusted": true,
"foreign_parts_only": false,
"ai_translated": false,
"machine_translated": false,
"upload_date": "2010-10-25T12:00:00Z",
"release": "Inception.2010.720p.BluRay.x264-REWARD",
"comments": "Sincronizado e Corrigido por ...",
"legacy_subtitle_id": 987654,
"uploader": {
"uploader_id": 54321,
"name": "NomeDoUploader",
"rank": "Administrador"
},
"feature_details": { // Informações sobre o filme/episódio
"feature_id": 5555,
"feature_type": "Filme",
"year": 2010,
"title": "A Origem",
"movie_name": "A Origem",
"imdb_id": "tt1375666",
"tmdb_id": 27205
},
"url": "<https://www.opensubtitles.org/en/subtitles/1234567/inception-en>",
"related_links": [
// ... links para conteúdo relacionado ...
],
"files": [ // CRUCIAL: Este array contém o(s) arquivo(s) para esta entrada de legenda
{
"file_id": 998877, // <<< ESTE é o ID necessário para o endpoint /download
"cd_number": 1,
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt"
}
// Potencialmente mais arquivos se for uma legenda multipart (ex: CD1, CD2)
]
}
},
// ... mais resultados de legendas ...
]
}
A informação mais importante necessária para o download é o file_id encontrado dentro do array attributes.files. Note que uma única entrada de legenda (data elemento do array) pode conter múltiplos arquivos (ex: para lançamentos mais antigos de CD1/CD2). Sua aplicação deve tipicamente selecionar o file_id apropriado com base em critérios como cd_number ou file_name.
Funcionalidade Principal: Baixando Legendas (/download)
Uma vez que você identificou o arquivo de legenda desejado usando o endpoint /subtitles e extraiu seu file_id, você pode usar o endpoint /download para obter um link temporário para o arquivo de legenda real.
Endpoint: POST /download
Propósito: Solicitar um link de download para um arquivo de legenda específico.
Autenticação: Requer cabeçalho Api-Key e autenticação de usuário válida (ou um token JWT logado no cabeçalho Authorization ou potencialmente permissões específicas da chave da API, dependendo da política da API – frequentemente o JWT é preferido/requerido para downloads para rastrear cotas).
Corpo da Requisição:
{
"file_id": 998877 // O file_id obtido dos resultados de busca
// Parâmetros opcionais como "sub_format", "file_name", "in_fps", "out_fps" podem estar disponíveis para conversão sob demanda
}
Cabeçalhos:
Content-Type: application/jsonAccept: application/jsonApi-Key: SUA_CHAVE_APIAuthorization: Bearer SEU_TOKEN_JWT (Provavelmente requerido) User-Agent: SeuNomeApp v1.0
Resposta Succesful (Exemplo):
{
"link": "<https://dl.opensubtitles.org/en/download/sub/1234567?uk=USER_KEY&uuid=RANDOM_UUID&filename=>...", // URL de download temporária
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt",
"requests": 5, // Número de requisições disponíveis para este link/arquivo específico? (Verifique a documentação)
"remaining": 95, // Cota de download restante do usuário para o dia/período
"message": "Contagem de download bem-sucedida.",
"reset_time": "2023-10-27T12:00:00Z", // Quando a cota de download pode ser reiniciada
"reset_time_utc": "2023-10-27T12:00:00Z"
}
Gerenciando o Download:
Faça a requisição POST para /download com o file_id correto. Verifique o código de status da resposta para sucesso (ex: 200 OK). Extraia o valor link da resposta JSON. Faça uma requisição HTTP GET padrão para esta URL link. Esta requisição não requer tipicamente os cabeçalhos da Chave da API ou de Autorização, pois o link em si já está pré-autorizado. A resposta à requisição GET na URL link será o conteúdo real do arquivo de legenda (ex: o texto do arquivo SRT). Salve este conteúdo em um arquivo (ex: usando a file_name fornecida).
Importante: Os links de download (link) geralmente são temporários e podem expirar após um curto período ou um certo número de usos. Não armazene esses links para uso a longo prazo; busque um novo link via o endpoint /download toda vez que um download for necessário. Ademais, monitore a contagem de download remaining para evitar esgotar a cota do usuário.
Recursos Avançados: Tradução AI (/ai-translation)
Uma adição mais recente ao conjunto de ferramentas do OpenSubtitles é o recurso de tradução impulsionado por IA.
Endpoint: POST /ai-translation (ou similar, verifique o endpoint exato na documentação)
Propósito: Traduzir um arquivo de legenda existente para outro idioma usando modelos de IA.
Como Funciona (Conceitual):
Você provavelmente fornece o file_id da legenda original que deseja traduzir. Você especifica o target_language (ex: target_language=de para alemão). A API processa a requisição, potencialmente colocando o trabalho de tradução em fila. A resposta pode indicar o status do trabalho ou fornecer um novo file_id ou link de download para a legenda traduzida uma vez que esteja concluída.
Casos de Uso:
Disponibilizar legendas em idiomas que não estavam originalmente presentes no banco de dados. Oferecer opções de tradução sob demanda dentro da sua aplicação.
Considerações:
Traduções por IA podem ter custos associados ou limites de taxa/cotas específicos, potencialmente atrelados a níveis VIP ou de assinatura. A qualidade da tradução por IA pode variar dependendo do par de idiomas e da complexidade do texto de origem. Este recurso pode exigir permissões específicas de usuário ou níveis de assinatura. Consulte a documentação da API para detalhes de uso, parâmetros e limitações.
Melhores Práticas para Integração com a API
Para garantir que sua aplicação interaja de maneira suave e responsável com a API do OpenSubtitles, siga estas melhores práticas:
Cache Respostas: Especialmente para resultados de busca (/subtitles) que não mudam rapidamente. Se um usuário busca pelo mesmo filme/episódio várias vezes, forneça o resultado em cache em vez de acessar a API repetidamente. Implemente cache inteligente com tempos de expiração razoáveis. Respeite Limites de Taxa: Monitore ativamente os cabeçalhos X-RateLimit-* e Retry-After. Implemente estratégias de backoff exponencial se você atingir o limite (espere mais após repetidas limitações de taxa). Não faça polling agressivamente na API. Use Identificadores Específicos: Sempre que possível, busque usando imdb_id ou tmdb_id em vez de query. Esses fornecem resultados muito mais precisos e reduzem ambiguidades. Use moviehash para a maior precisão se o arquivo de vídeo estiver disponível. Forneça um User-Agent Claro: Use uma string User-Agent única e descritiva (ex: MeuReprodutorDeMidia/2.1 (contato@meuapp.com)). Isso ajuda o OpenSubtitles a identificar fontes de tráfego e resolver problemas. Agentes genéricos podem ser bloqueados. Gerencie Erros de Forma Elegante: Verifique códigos de status HTTP para cada resposta. Implemente lógica para lidar com erros comuns como 401 Não Autorizado (chave API/JWT inválido), 403 Proibido (permissão negada), 404 Não Encontrado, 429 Muitas Requisições e erros de servidor 5xx. Forneça feedback informativo ao usuário. Gerencie Cotizações de Download: Esteja ciente dos limites diários/periódicos de download associados à conta do usuário (ou chave da API). Informe os usuários se estão se aproximando ou excedendo sua cota. Use o campo remaining na resposta /download. Otimize Buscas: Não solicite dados desnecessários. Use parâmetros como languages, type, hearing_impaired, etc., para restringir resultados do lado do servidor em vez de filtrar conjuntos de dados grandes do lado do cliente. Proteja Sua Chave da API: Trate sua Chave da API como uma senha. Não a incorpore diretamente no código do lado do cliente. Armazene-a com segurança em seu servidor.
Wrappers, Scripts e Recursos da Comunidade
Embora este guia aborde a interação direta com a API, o ecossistema do OpenSubtitles geralmente inclui recursos desenvolvidos pela comunidade.
Wrappers da API: Procure por bibliotecas ou SDKs para sua linguagem de programação (ex: Python, JavaScript, Java) em plataformas como GitHub ou gerenciadores de pacotes (PyPI, npm). Esses wrappers podem simplificar chamadas de API, gerenciar autenticação e analisar respostas. Scripts: Vários ferramentas de linha de comando ou scripts podem existir para interagir com a API, úteis para automação ou buscas rápidas. Fóruns/Comunidades: Verifique fóruns do OpenSubtitles ou comunidades de desenvolvedores relacionadas para discussões, exemplos e potenciais ferramentas de terceiros utilizando a API.
Usar um wrapper bem mantido pode acelerar significativamente o desenvolvimento, mas entender as chamadas de API subjacentes (como descrito neste guia) permanece crucial para solução de problemas e uso avançado.
Assinatura da API e Preços
O OpenSubtitles normalmente oferece diferentes níveis de acesso à sua API:
Nível Gratuito: Geralmente fornece acesso básico com limites de taxa mais rígidos e cotas de download. Adequado para aplicações de baixo volume ou desenvolvimento/teste. Níveis VIP/Pagos: Oferecem limites de taxa significativamente mais altos, maiores cotas de download, acesso a recursos premium (como potencialmente Tradução AI ou suporte mais rápido) e são destinados a aplicações comerciais ou de alto tráfego.
Consulte a documentação oficial da API do OpenSubtitles ou o site para os detalhes mais atuais sobre planos de assinatura, preços e os limites/recursos específicos associados a cada nível. Escolha o plano que melhor corresponda ao uso esperado e aos requisitos de recursos da sua aplicação.
Conclusão
A API do OpenSubtitles é um poderoso portal para uma das maiores coleções de legendas do mundo. Ao entender sua estrutura, métodos de autenticação, endpoints principais como /subtitles e /download, e aderir às melhores práticas, os desenvolvedores podem integrar sem esforço a funcionalidade de legendas em suas aplicações. Desde buscas simples em reprodutores de mídia até recursos complexos envolvendo tradução por IA, a API fornece os fundamentos para experiências inovadoras e amigáveis ao usuário. Lembre-se de consultar a documentação oficial da API do OpenSubtitles para os detalhes mais atualizados sobre endpoints, parâmetros e políticas enquanto você embarca em sua jornada de desenvolvimento. Boa codificação!