자막은 현대 미디어 경험의 필수 불가결한 부분입니다. 자막은 언어 장벽을 허물고, 청각 장애인을 위한 접근성을 향상시키며, 전 세계의 언어 학습자를 돕습니다. 자막 접근성의 핵심에는 자막 파일을 위한 가장 크고 인기 있는 온라인 데이터베이스 중 하나인 OpenSubtitles가 있습니다. 하지만 OpenSubtitles는 단순히 웹사이트 이상의 의미가 있습니다. 개발자들이 방대한 자막 데이터베이스를 직접 자신의 애플리케이션에 통합할 수 있도록 강력한 REST API를 제공합니다.
미디어 플레이어, 콘텐츠 관리 시스템, 언어 학습 도구 또는 자막 통합의 혜택을 받을 수 있는 애플리케이션을 만들고 있다면 OpenSubtitles API가 필요한 도구를 제공합니다. 이 포괄적인 가이드는 초기 설정 및 인증부터 자막 검색, 다운로드, 번역 및 모범 사례 준수에 이르기까지 OpenSubtitles API를 효과적으로 활용하는 데 필요한 모든 것을 안내합니다.
개발 팀이 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하십니까? 최대 생산성을 발휘하시겠습니까?
Apidog는 모든 요구 사항을 충족시키며, Postman을 훨씬 더 저렴한 가격으로 대체합니다!
버튼
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는 두 가지 주요 인증 방법을 지원합니다:
API 키: 가장 간단한 방법입니다. 모든 요청의 Api-Key 헤더에 API 키를 포함하세요. Api-Key: YOUR_API_KEY JWT 토큰: 더 많은 사용자 맞춤 기능이나 다른 비율 제한(API 설계에 따라 사용자 맞춤 기능)을 접근할 수 있도록 /login 엔드포인트에 로그인하여 JSON 웹 토큰(JWT)을 얻을 수 있습니다(나중에 다룸). 이 토큰은 Authorization 헤더에 Bearer 토큰으로 포함됩니다. 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-Agents(예: 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: 비율 제한 창이 재설정되는 타임스탬프(종종 유닉스 에포크 시간). 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 사용:
획득한 후 이 token 값을 후속 요청의 Authorization 헤더에 포함합니다:
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>: 영화 데이터베이스(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>: 정렬 방향을 지정합니다.
예시 검색 요청 (TMDb ID를 통해 "Inception"의 영어 자막 찾기):
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 키 권한이 있을 수 있음, 정책에 따라 다름 - 일반적으로 다운로드를 추적하기 위해 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"
}
다운로드 처리:
/download에 올바른 file_id로 POST 요청을 하세요. 응답 상태 코드를 확인하여 성공 여부(예: 200 OK)를 확인합니다. JSON 응답에서 link 값을 추출합니다. 이 link URL에 대해 표준 HTTP GET 요청을 합니다. 이 요청은 일반적으로 API 키나 인증 헤더가 필요하지 않습니다. 링크 자체가 사전 승인되었기 때문입니다. link URL에 대한 GET 요청의 응답은 실제 자막 파일 내용(예: SRT 파일의 텍스트)이 될 것입니다. 이 내용을 파일(e.g., 제공된 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를 공격적으로 폴링하지 마세요. 구체적인 식별자 사용: 가능한 한 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 래퍼: GitHub나 패키지 관리자(PyPI, npm)와 같은 플랫폼에서 여러분의 프로그래밍 언어(예: Python, JavaScript, Java)에 대한 라이브러리나 SDK를 찾아보세요. 이 래퍼들은 API 호출을 간소화하고 인증을 처리하며 응답을 파싱할 수 있습니다. 스크립트: API와 상호작용하기 위한 다양한 명령줄 도구나 스크립트가 존재할 수 있으며, 이들은 자동화 또는 빠른 조회에 유용합니다. 포럼/커뮤니티: OpenSubtitles 포럼이나 관련 개발자 커뮤니티를 확인하여 논의, 예제 및 API를 활용하는 제3자 도구를 찾아보세요.
잘 관리되는 래퍼를 사용하면 개발 속도가 크게 빨라질 수 있지만, 문제 해결 및 고급 사용을 위해서는 기본적인 API 호출을 이해하는 것이 중요합니다(이 가이드에 설명된 대로).
API 구독 및 가격
OpenSubtitles는 일반적으로 API에 대한 다양한 액세스 수준을 제공합니다:
무료 등급: 일반적으로 더 엄격한 비율 제한 및 다운로드 쿼터와 함께 기본 액세스를 제공합니다. 낮은 볼륨의 애플리케이션이나 개발/테스트에 적합합니다. VIP/유료 등급: 훨씬 더 높은 비율 제한, 더 큰 다운로드 쿼터, 프리미엄 기능(잠재적으로 AI 번역 또는 더 빠른 지원) 접근을 제공하며, 상업적이거나 고트래픽 애플리케이션을 위해 의도되었습니다.
현재 구독 계획, 가격 및 각 등급과 관련된 특정 제한/기능에 대한 자세한 내용은 공식 OpenSubtitles API 문서나 웹사이트를 참조하세요. 애플리케이션의 예상 사용량 및 기능 요구 사항에 가장 잘 맞는 계획을 선택하세요.
결론
OpenSubtitles API는 세계에서 가장 큰 자막 컬렉션 중 하나에 대한 강력한 게이트웨이입니다. 그 구조, 인증 방법, /subtitles 및 /download와 같은 핵심 엔드포인트를 이해하고 모범 사례를 준수함으로써 개발자는 자막 기능을 자신의 애플리케이션에 원활하게 통합할 수 있습니다. 미디어 플레이어에서 간단한 조회부터 AI 번역과 관련된 복잡한 기능에 이르기까지, 이 API는 혁신적이고 사용자 친화적인 경험을 위한 기초를 제공합니다. 개발 여정을 시작할 때 가장 최신의 엔드포인트 세부정보, 매개변수 및 정책에 대한 공식 OpenSubtitles API 문서를 참고하세요. 행복한 코딩 되세요!