OpenSubtitles APIの使い方

字幕は現代のメディア体験に欠かせない部分です。字幕は言語の壁を越え、聴覚障害者のためのアクセシビリティを向上させ、世界中の言語学習者を支援します。字幕のアクセシビリティの中心には、字幕ファイルの最大かつ最も人気のあるオンラインリポジトリの一つであるOpenSubtitlesがあります。しかし、OpenSubtitlesは単なるウェブサイト以上のものです。開発者がその広大な字幕データベースを直接アプリケーションに統合できる強力なREST APIを提供しています。

メディアプレーヤー、コンテンツ管理システム、言語学習ツール、または字幕統合から利益を得ることができる任意のアプリケーションを構築している場合、OpenSubtitles APIは必要なツールを提供します。この包括的なガイドでは、初期設定と認証から字幕の検索、ダウンロード、翻訳、ベストプラクティスの遵守に至るまで、OpenSubtitles APIを効果的に活用するために必要なことをすべて紹介します。

OpenSubtitles APIとは？

OpenSubtitles APIは、開発者がプログラムを通じてOpenSubtitlesデータベースと相互作用するための一連のプログラミングインターフェースです。ウェブサイトから手動で字幕を検索してダウンロードするのではなく、アプリケーションはAPIを使用してこれらのアクションを自動的に実行できます。これにより、シームレスで機能豊富なユーザーエクスペリエンスを作成するための可能性の世界が開かれます。

主な機能:

検索: 映画や番組のタイトル、IMDB ID、TMDB ID、ファイルハッシュ、言語などのさまざまな基準に基づいて字幕を見つけます。 ダウンロード: 検索結果を通じて特定の字幕ファイルを取得します。 AI翻訳: 既存の字幕を異なる言語に翻訳するために人工知能を活用します。 情報取得: 字幕およびメディアに関するメタデータにアクセスします。

始めるには: 最初のステップ

APIにリクエストを送信する前に、理解すべきいくつかの前提条件と基本コンセプトがあります。

1. APIエンドポイント:

OpenSubtitlesのREST APIとのすべてのやりとりは、単一の基本URLを介して行われます:

https://api.opensubtitles.com/api/v1

すべての特定のエンドポイント（検索やダウンロードなど）は、この基本URLに追加されます。

2. 登録とAPIキー:

APIにアクセスするには認証が必要です。主な方法はAPIキーを使用することです。

登録: まず、OpenSubtitlesのアカウントが必要です。アカウントがない場合は、彼らのウェブサイトで登録してください。 APIキーを取得: 登録が完了したら、APIキーを生成する必要があります。これは一般的にユーザープロファイルまたはOpenSubtitlesウェブサイトの専用開発者セクションを通じて行われます。APIキーはアプリケーションのリクエストを特定するため、安全に保管してください。

3. 認証:

APIは2つの主要な認証方法をサポートしています:

APIキー: 最も簡単な方法です。すべてのリクエストのApi-KeyヘッダーにAPIキーを含めます。 Api-Key: YOUR_API_KEY    JWTトークン: ユーザー特有の機能や異なるレート制限にアクセスするために、/loginエンドポイントを通じてログインしてJSON Web Token（JWT）を取得できます（後で詳しく説明します）。このトークンは次に、BearerトークンとしてAuthorizationヘッダーに含めます。 Authorization: Bearer YOUR_JWT_TOKEN
JWTトークンを使用する場合でも、アプリケーションの識別のために一般的にはApi-Keyヘッダーを提供する必要があります。

4. 必要なヘッダー:

認証ヘッダーの他に、すべてのAPIリクエストには必ず次を含める必要があります:

Content-Type: ボディを持つリクエスト（POSTリクエストなど）の場合、通常はapplication/jsonを指定します。 Content-Type: application/json    **User-Agent:** これは重要です。APIはアプリケーションを特定する説明的なUser-Agent文字列を必要とします。あいまいまたはデフォルトのUser-Agent（例えばpython-requests）はブロックされる可能性があります。良いフォーマットはYourAppName v1.0です。 User-Agent: MySubtitleApp v1.2.3

5. レート制限:

ほとんどの公開APIと同様に、OpenSubtitlesは公正な使用とサーバの安定性を確保するためにレート制限を設けています。これらの制限を超えると、エラー応答（多くの場合、429 Too Many Requests）が返されます。リクエストレートを管理するために、以下のレスポンスヘッダーに注意を払ってください:

X-RateLimit-Limit: 現在のウィンドウ内で許可されるリクエストの最大数。 X-RateLimit-Remaining: 現在のウィンドウ内の残りのリクエスト数。 X-RateLimit-Reset: レート制限ウィンドウがリセットされるタイムスタンプ（多くの場合、Unixエポック時間）。 Retry-After: 429エラーが返された場合、このヘッダーは再試行する前に待つべき秒数を示します。

これらのヘッダーを尊重してアプリケーション内でロジックを実装することが、信頼性のある操作のために重要です。

認証の深堀り: /loginエンドポイント

APIキーを使用するだけで十分なことが多いですが、/loginエンドポイントを使用すると、アプリケーションが特定のOpenSubtitlesユーザーとして認証され、JWTを取得できます。

エンドポイント: POST /login

目的: ユーザーの資格情報（ユーザー名/パスワード）をJWT認証トークンに交換します。

リクエストボディ:

{
  "username": "your_opensubtitles_username",
  "password": "your_opensubtitles_password"
}

ヘッダー:

Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYUser-Agent: YourAppName v1.0

成功したレスポンス（例）:

{
  "user": {
    "allowed_downloads": 100,
    "level": "Sub leecher",
    "user_id": 123456,
    "ext_installed": false,
    "vip": false
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // これがJWTです
  "status": 200
}

JWTの使用:

取得したら、以降のリクエストのAuthorizationヘッダーにこのtoken値を含めます:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWTを使用することで、ユーザー特有のダウンロードクオータやVIPステータスに関連した他の機能にアクセスできる場合があります。JWTは通常、期限が設定されているため、定期的に再認証が必要になることがあります。

コア機能: 字幕の検索 (/subtitles)

これは最も頻繁に使用されるエンドポイントかもしれません。OpenSubtitlesデータベースをクエリすることを可能にします。

エンドポイント: GET /subtitles

目的: 様々な検索基準に基づいて字幕を見つけます。

認証: Api-Keyヘッダーが必要です（オプションでAuthorization: Bearer <token>を含めることもできます）。

主要なクエリパラメータ:

検索の力は、その柔軟なクエリパラメータにあります。必要に応じてこれらを組み合わせることができます:

query=<string>: 映画またはエピソードのタイトルで検索します（例: query=The Matrix, query=Game of Thrones S01E01）。 imdb_id=<string>: IMDb IDを使用して検索します（例: imdb_id=tt0133093）。これはqueryよりも正確であることが多いです。 tmdb_id=<integer>: The Movie Database (TMDb) IDを使用して検索します（例: tmdb_id=603）。非常に正確です。 parent_tmdb_id=<integer>: エピソードを検索する場合、ショーのTMDb IDを使用します（例: parent_tmdb_id=1399はGame of Thronesのものです）。 season_number=<integer>: 特定のシーズンの字幕を見つけるためにparent_tmdb_id（またはショーのimdb_id）と組み合わせて使用します。 episode_number=<integer>: 特定のエピソードのためにparent_tmdb_id（またはimdb_id）とseason_numberを組み合わせて使用します。 languages=<string>: 言語コードでフィルタリングします（カンマ区切り、例: languages=en,es, languages=fr）。ISO 639-2Bコードを使用します（例: eng, spa, fre）。 moviehash=<string>: 動画ファイルから計算されたユニークなハッシュを使用して検索します。動画ファイル自体がある場合、最も正確な一致を提供します。このハッシュを計算するには、通常特定のライブラリやツールが必要です。 type=<string>: タイプ（movieまたはepisode）でフィルタリングします。 hearing_impaired=<include|exclude|only>: 聴覚障害者向けにデザインされた字幕をフィルタリングします。 machine_translated=<include|exclude|only>: 字幕が機械翻訳されたかどうかに基づいてフィルタリングします。 ai_translated=<include|exclude|only>: APIのAI機能を使用して翻訳された字幕に基づいてフィルタリングします。 order_by=<field>: 結果をソートします（例: order_by=download_count）。 order_direction=<asc|desc>: ソートの方向を指定します。

例: "Inception"の英語字幕をTMDb ID経由で見つけるリクエスト:

GET /api/v1/subtitles?tmdb_id=27205&languages=en HTTP/1.1
Host: api.opensubtitles.com
Api-Key: YOUR_API_KEY
User-Agent: MySubtitleApp v1.0
Accept: application/json

検索結果の解釈:

レスポンスは、data配列を含むJSONオブジェクトです。配列内の各要素は字幕の一致を表します。

{
  "total_pages": 10,
  "total_count": 195,
  "per_page": 20,
  "page": 1,
  "data": [
    {
      "id": "1234567", // 字幕ID（ダウンロードには有用だが必ずしも必要ではない）
      "type": "subtitles",
      "attributes": {
        "subtitle_id": "1234567", // レガシーID
        "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": "Sync and Corrected by ...",
        "legacy_subtitle_id": 987654,
        "uploader": {
          "uploader_id": 54321,
          "name": "UploaderName",
          "rank": "Administrator"
        },
        "feature_details": { // 映画/エピソードに関する情報
          "feature_id": 5555,
          "feature_type": "Movie",
          "year": 2010,
          "title": "Inception",
          "movie_name": "Inception",
          "imdb_id": "tt1375666",
          "tmdb_id": 27205
        },
        "url": "<https://www.opensubtitles.org/en/subtitles/1234567/inception-en>",
        "related_links": [
          // ... 関連コンテンツへのリンク ...
        ],
        "files": [ // 重要: この配列はこの字幕エントリのファイルを含みます
          {
            "file_id": 998877, // <<< これが/downloadエンドポイントに必要なIDです
            "cd_number": 1,
            "file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt"
          }
          // 複数パートの字幕の場合はさらに多くのファイルが含まれる可能性があります（例: CD1、CD2）
        ]
      }
    },
    // ... さらに多くの字幕結果 ...
  ]
}

ダウンロードに必要な最も重要な情報は、attributes.files配列に見つかるfile_idです。単一の字幕エントリ（data配列の要素）は、複数のファイルを含むことがあります（古いCD1/CD2リリースの場合など）。アプリケーションは、通常、cd_numberやfile_nameなどの基準に基づいて適切なfile_idを選択するべきです。

コア機能: 字幕のダウンロード (/download)

字幕ファイルの/subtitlesエンドポイントを使用して目的の字幕ファイルを特定し、file_idを抽出したら、/downloadエンドポイントを使用して実際の字幕ファイルの一時リンクを取得できます。

エンドポイント: POST /download

目的: 特定の字幕ファイルのダウンロードリンクをリクエストします。

認証: Api-Keyヘッダーと有効なユーザー認証（認証トークンとしてログインしたJWTトークンをAuthorizationヘッダーに含めるまたは、APIポリシーに応じて特定のAPIキー権限を使用することが必要です - 多くの場合、クオータを追跡するためにダウンロードにはJWTが推奨・必要です）を必要とします。

リクエストボディ:

{
  "file_id": 998877 // 検索結果から取得したfile_id
  // "sub_format", "file_name", "in_fps", "out_fps" などのオプションパラメータが即時変換のために使用できる場合があります。
}

ヘッダー:

Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYAuthorization: Bearer YOUR_JWT_TOKEN（おそらく必要） User-Agent: YourAppName v1.0

成功したレスポンス（例）:

{
  "link": "<https://dl.opensubtitles.org/en/download/sub/1234567?uk=USER_KEY&uuid=RANDOM_UUID&filename=>...", // 一時ダウンロードURL
  "file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt",
  "requests": 5, // この特定のリンク/ファイルの利用可能なリクエスト数（ドキュメントを確認）
  "remaining": 95, // ユーザーの残りのダウンロードクオータ（日/期間）
  "message": "ダウンロード数成功。",
  "reset_time": "2023-10-27T12:00:00Z", // ダウンロードクオータがリセットされる時刻
  "reset_time_utc": "2023-10-27T12:00:00Z"
}

ダウンロードの処理:

正しいfile_idで/downloadにPOSTリクエストを行います。成功のためにレスポンスステータスコードを確認します（例: 200 OK）。JSONレスポンスからlink値を抽出します。このlink URLに対して標準的なHTTP GETリクエストを行います。このリクエストでは通常、APIキーや認証ヘッダーは必要ありません。なぜなら、そのリンク自体が事前に認可されているからです。link URLに対するGETリクエストのレスポンスは、実際の字幕ファイルの内容（例: SRTファイルのテキスト）になります。この内容をファイルに保存します（例: 提供されたfile_nameを使用して）。

重要: ダウンロードリンク（link）は通常一時的であり、短い期間や一定回数の使用後に期限切れになる可能性があります。これらのリンクを長期間保存しないでください。ダウンロードが必要なたびに/downloadエンドポイントを介して新しいリンクを取得してください。また、ユーザーのクオータが尽きないようにremainingダウンロード数を監視してください。

高度な機能: AI翻訳 (/ai-translation)

OpenSubtitlesツールキットに最近追加された機能は、AIによる翻訳機能です。

エンドポイント: POST /ai-translation（または類似のエンドポイント、ドキュメントで正確なエンドポイントを確認してください）

目的: 既存の字幕ファイルをAIモデルを使用して別の言語に翻訳します。

仕組み（概念的）:

翻訳したいソース字幕のfile_idを提供します。target_languageを指定します（例: target_language=deはドイツ語用）。APIはリクエストを処理し、翻訳ジョブをキューに入れる可能性があります。レスポンスには、ジョブのステータスが表示されるか、翻訳された字幕の新しいfile_idまたはダウンロードリンクが提供されるかもしれません。

ユースケース:

データベースに元々存在しない言語で字幕を提供すること。アプリケーション内でオンデマンド翻訳オプションを提供すること。

考慮事項:

AI翻訳には関連するコストや特定のレート制限/クオータがある可能性があり、VIPやサブスクリプションレベルに関連していることがあります。AI翻訳の品質は言語ペアやソーステキストの複雑さに応じて異なる場合があります。この機能は特定のユーザー権限やサブスクリプションレベルを必要とするかもしれません。使用法、パラメータ、および制限についてはAPIドキュメントを確認してください。

API統合のベストプラクティス

あなたのアプリケーションがOpenSubtitles APIとスムーズかつ責任を持って相互作用することを確保するために、以下のベストプラクティスに従ってください:

レスポンスをキャッシュ: 特に、急速に変化しない検索結果（/subtitles）に対して。ユーザーが同じ映画/エピソードを複数回検索する場合、APIを繰り返し呼び出さずにキャッシュされた結果を提供します。合理的な有効期限を持つインテリジェントなキャッシングを実装してください。 レート制限を尊重: X-RateLimit-*およびRetry-Afterヘッダーを積極的に監視します。制限に達した場合には指数バックオフ戦略を実装します（繰り返しレート制限に遭った後は、より長く待つ）。APIを過剰にポーリングしないでください。 特定の識別子を使用: 可能な限り、queryよりもimdb_idやtmdb_idを使用して検索します。これにより、より正確な結果が得られ、あいまいさが減ります。動画ファイルが入手可能な場合は、最高の精度を得るためにmoviehashを使用します。 明確なUser-Agentを提供: ユニークで説明的なUser-Agent文字列を使用します（例: MyMediaPlayerApp/2.1 (contact@myapp.com)）。これによりOpenSubtitlesはトラフィックソースを特定し、問題をトラブルシュートするのに役立ちます。一般的なエージェントはブロックされる可能性があります。 エラーを優雅に処理: すべてのレスポンスのHTTPステータスコードを確認します。401 Unauthorized（無効なAPIキー/JWT）、403 Forbidden（権限が拒否された）、404 Not Found、429 Too Many Requests、および5xxサーバーエラーなどの一般的なエラーを処理するロジックを実装します。ユーザーへの情報提供を行ってください。 ダウンロードクオータを管理: ユーザーのアカウント（またはAPIキー）に関連する日次/定期的なダウンロード制限に注意してください。ユーザーがクオータに近づいているか、または超えた場合にはその旨を通知してください。/downloadレスポンス内のremainingフィールドを使用します。 検索を最適化: 不要なデータをリクエストしないでください。languages、type、hearing_impairedなどのパラメータを使用して、サーバー側で結果を絞り込み、大規模なデータセットをクライアント側でフィルタリングしないでください。 APIキーを安全に保管: APIキーをパスワードと同様に扱います。クライアント側のコードに直接埋め込まないでください。サーバー上で安全に保管してください。

ラッパー、スクリプト、コミュニティリソース

このガイドではAPIとの直接的な相互作用をカバーしていますが、OpenSubtitlesのエコシステムにはしばしばコミュニティ開発のリソースが含まれます。

APIラッパー: プログラミング言語用のライブラリやSDKを、GitHubやパッケージマネージャー（PyPI、npm）で探してください。これらのラッパーはAPI呼び出しを簡素化し、認証を処理し、レスポンスを解析できます。 スクリプト: APIと相互作用するためのさまざまなコマンドラインツールやスクリプトが存在するかもしれません。自動化やクイックルックアップに便利です。 フォーラム/コミュニティ: OpenSubtitlesフォーラムや関連する開発者コミュニティを確認して、議論、例、APIを利用する可能性のあるサードパーティツールを探してください。

良好に保たれているラッパーを使用すると、開発のスピードが大幅に向上しますが、このガイドで説明した基礎的なAPI呼び出しを理解することは、トラブルシューティングや高度な使用に不可欠です。

APIサブスクリプションと料金

OpenSubtitlesは通常、APIへの異なるアクセスレベルを提供しています:

無料プラン: 通常、より厳しいレート制限とダウンロードクオータを持つ基本アクセスを提供します。低ボリュームのアプリケーションや開発/テストに適しています。 VIP/有料プラン: 非常に高いレート制限、より大きなダウンロードクオータ、プレミアム機能（AI翻訳や迅速なサポートの可能性など）へのアクセスを提供し、商業用または高トラフィックアプリケーション向けです。

サブスクリプションプラン、料金、各プランに関連する特定の限界/機能については、公式のOpenSubtitles APIドキュメントまたはウェブサイトを参照してください。アプリケーションの予想される使用状況と機能要件に最も適したプランを選択してください。

結論

OpenSubtitles APIは、世界最大級の字幕コレクションへの強力なゲートウェイです。その構造、認証方法、/subtitlesや/downloadのようなコアエンドポイントを理解し、ベストプラクティスに従うことで、開発者は自分のアプリケーションに字幕機能をシームレスに統合できます。メディアプレーヤーでの単純な検索から、AI翻訳を含む複雑な機能に至るまで、APIは革新的で使いやすい体験のための構成要素を提供します。開発を始めるにあたり、最新のエンドポイントの詳細、パラメータ、およびポリシーについては、公式のOpenSubtitles APIドキュメントを確認してください。コーディングを楽しんでください！