TMDB API 키 발급 및 TMDB API 쿼리 방법

영화 데이터베이스(TMDB)는 영화, TV 프로그램, 출연진 및 아트워크를 커뮤니티가 구축한 카탈로그입니다. TMDB의 API는 비상업적 용도로는 무료로 사용할 수 있으며, TMDB에 크레딧을 제공해야 합니다. 이 점 때문에 무료 영화 API 목록에서 가장 일반적인 시작점이 됩니다. 단점은 온보딩 과정인데, TMDB는 두 가지 다른 자격 증명을 제공하며, 공식 시작하기 가이드는 어떤 것을 사용해야 할지 이미 알고 있다고 가정합니다.

이 가이드는 계정 생성, 키 요청, v3 키와 v4 읽기 액세스 토큰의 차이점, curl 및 Python에서 첫 검색 및 상세 정보 호출, Apidog에 테스트로 저장된 동일한 호출, 그리고 첫날에 접하게 될 속도 제한, 귀속 규칙 및 오류에 이르는 전체 과정을 다룹니다.

button

시작하기 전에 필요한 것

인증된 이메일 주소를 가진 TMDB 계정. API는 인증되지 않은 계정에 대해 401 오류를 반환합니다.
데스크톱 브라우저. TMDB 문서에 따르면 API 등록 페이지는 모바일 기기에 최적화되어 있지 않습니다.
`requests` 패키지가 설치된 curl 또는 Python 3.
토큰을 안전하게 저장하고 요청을 관리할 Apidog. macOS, Windows 또는 Linux용 Apidog 다운로드.

1단계: TMDB 계정 생성

themoviedb.org로 이동하여 "Join TMDB"를 클릭하고 이메일 주소로 가입하세요. API 설정을 건드리기 전에 인증 이메일을 열어 확인하세요. 이 단계를 건너뛰면 나중에 혼란스러운 401 오류, 상태 코드 32: "Email not verified: Your email address has not been verified."를 만나게 될 것입니다.

2단계: API 키 요청

로그인 후 계정 설정으로 이동하여 왼쪽 사이드바에서 "API"를 클릭하세요. TMDB의 FAQ는 이를 유일한 경로로 설명합니다: "계정 설정 페이지의 왼쪽 사이드바에 있는 'API' 링크를 클릭하여 API 키를 신청할 수 있습니다."

API 이용 약관에 동의한 다음, 만들고 있는 것, URL(있는 경우), 데이터 사용 방법에 대한 요약, 사용 유형을 포함하는 짧은 신청서를 작성해야 합니다. 개인 프로젝트, 프로토타입, 내부 도구의 경우 개발자 옵션을 선택하세요. TMDB는 프로젝트의 "주요 목적이 소유자의 이익을 위한 수익 창출"인 경우 상업적인 것으로 간주하며, 이 경우 영업팀과의 서면 계약이 필요합니다.

제출 후, 동일한 설정 페이지에 두 가지 자격 증명이 표시됩니다:

API 키, v3 인증용으로 표시됩니다. 32자 헥스 문자열입니다.
API 읽기 액세스 토큰, 훨씬 더 긴 JWT 스타일의 문자열입니다.

TMDB는 검토 일정을 공개하지 않으며, 실제로는 양식 제출 즉시 두 값이 모두 나타납니다. 다른 비밀 정보와 마찬가지로 취급하고 커밋, 채팅 창, 스크린샷에 노출되지 않도록 주의하세요.

v3 API 키 대 v4 읽기 액세스 토큰

두 자격 증명은 "오래된 것"과 "새로운 것"이 아닙니다. 이들은 동일한 애플리케이션을 식별하는 두 가지 방법이며, 공식 인증 문서에는 둘 다 "동일한 수준의 접근 권한을 제공한다"고 명시되어 있습니다.

	API 키 (v3)	API 읽기 액세스 토큰
전송 방법	쿼리 파라미터: `?api_key=YOUR_KEY`	헤더: `Authorization: Bearer YOUR_TOKEN`
호환 대상	`/3/` 아래의 v3 엔드포인트	v3 및 v4 엔드포인트
TMDB 기본 설정	아니요	예
서버 로그 및 브라우저 기록에 표시	예, URL에 있습니다	아니요

TMDB 자체 권장 사항은 Bearer 토큰입니다: "인증의 기본 방법은 액세스 토큰을 사용하는 것"이며, 이는 "v3 및 v4 메서드 모두에서 사용할 수 있는 단일 인증 프로세스라는 추가적인 이점"을 가집니다.

클라이언트가 헤더를 설정할 수 없는 경우가 아니라면 Bearer 헤더를 사용하세요. URL에서 자격 증명을 제외하는 것은 모든 API 키 대 Bearer 토큰 결정의 배경과 동일한 주장입니다: URL은 로깅되고, 캐시되며, 공유될 수 있습니다.

한 가지 더 구별할 점입니다. 이 글의 모든 내용은 읽기 전용 카탈로그 데이터이며, 애플리케이션 자격 증명만 있으면 됩니다. v4 API는 목록, 즐겨찾기, 평점, 시청 목록과 같은 계정 기능을 추가합니다. TMDB 사용자를 위해 이러한 기능을 작성하려면 추가적인 핸드셰이크가 필요합니다: /4/auth/request_token에서 요청 토큰을 받고, 사용자 승인을 거쳐, /4/auth/access_token에서 사용자 액세스 토큰을 받아야 합니다. 영화를 검색하거나 세부 정보를 읽는 데는 이러한 과정이 필요하지 않습니다.

3단계: 첫 요청 보내기

모든 v3 호출은 https://api.themoviedb.org/3으로 전송됩니다. 대부분의 첫 프로젝트에는 두 가지 엔드포인트가 사용됩니다: 제목으로 검색한 다음 ID로 상세 정보를 가져오는 것입니다.

curl을 사용하여 영화 검색

curl --request GET \
  --url 'https://api.themoviedb.org/3/search/movie?query=fight%20club&include_adult=false&language=en-US&page=1' \
  --header 'Authorization: Bearer YOUR_READ_ACCESS_TOKEN' \
  --header 'accept: application/json'

응답은 page, results, total_pages, total_results를 포함하는 페이지 객체입니다. 각 결과에는 id, title, release_date, overview, poster_path, genre_ids, vote_average가 포함됩니다. TMDB 자체 검색 예시에서 "fight club"에 대한 첫 번째 결과는 ID 550이며, 1999년 10월 15일에 개봉되었습니다.

v3 키를 사용한 동일한 호출은 다음과 같습니다. 인증 헤더가 전혀 없다는 점에 유의하세요:

curl 'https://api.themoviedb.org/3/search/movie?query=fight%20club&api_key=YOUR_API_KEY'

Python으로 영화 상세 정보 가져오기

이제 검색에서 얻은 ID를 사용하여 전체 레코드를 요청합니다. 영화 상세 정보 엔드포인트는 runtime, genres, budget, revenue, overview를 반환합니다. append_to_response 파라미터는 동일한 왕복 요청에 크레딧과 같은 하위 리소스를 추가하며, 요청당 최대 20개까지 가능합니다.

import os
import requests

TOKEN = os.environ["TMDB_READ_ACCESS_TOKEN"]
BASE = "https://api.themoviedb.org/3"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "accept": "application/json"}


def search_movie(title):
    r = requests.get(
        f"{BASE}/search/movie",
        params={"query": title, "include_adult": "false", "language": "en-US"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["results"]


def movie_details(movie_id):
    r = requests.get(
        f"{BASE}/movie/{movie_id}",
        params={"append_to_response": "credits"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()


hit = search_movie("Fight Club")[0]
movie = movie_details(hit["id"])
print(movie["title"], movie["release_date"], f'{movie["runtime"]} min')
print("https://image.tmdb.org/t/p/w500" + movie["poster_path"])

마지막 줄은 사람들이 놓치는 부분입니다. poster_path는 단순히 경로일 뿐입니다. 이미지 기본 가이드에서 설명하듯이, 작동하는 URL은 https://image.tmdb.org/t/p/, 그 다음 w500 또는 original과 같은 크기, 그리고 경로로 구성됩니다. /3/configuration은 모든 유효한 크기를 나열합니다.

4단계: Apidog에서 요청 실행 및 저장

원시 호출이 작동하면, 잃어버리지 않도록 어딘가에 옮겨두세요. Apidog에서는 몇 분이면 이 작업을 완료하고 저장되고 공유 가능한 테스트를 남길 수 있습니다.

두 개의 변수를 가진 "TMDB"라는 환경으로 프로젝트를 생성하고 추가합니다: base_url은 https://api.themoviedb.org/3으로 설정하고, tmdb_token에는 읽기 액세스 토큰을 저장합니다. 토큰을 비밀로 표시하여 UI에서 마스킹되고 내보내기에서 제외되도록 합니다. 환경 및 비밀 변수 가이드에서 옵션을 확인할 수 있습니다.
query 파라미터와 함께 {{base_url}}/search/movie에 GET 요청을 추가합니다. Auth 탭에서 Bearer Token을 선택하고 {{tmdb_token}}을 입력합니다. 요청을 보내고 200 응답과 results 배열을 받는지 확인합니다.
{{base_url}}/movie/{{movie_id}}에 두 번째 GET 요청을 추가합니다. 첫 번째 요청의 후처리에서 results[0].id를 movie_id로 추출하여 두 번째 호출이 항상 첫 번째 호출을 따르도록 합니다.
두 요청을 테스트 시나리오로 저장하고 어설션(assertion)을 추가합니다: 상태 코드는 200, total_results는 0보다 크고, 상세 응답의 title은 비어 있지 않습니다. 통합 변경 시마다 실행하세요.

이 데이터를 기반으로 프론트엔드를 구축하시나요? 검색 엔드포인트에 대한 목(mock) 서버를 켜세요. Apidog는 스키마와 일치하는 응답을 생성하므로, UI 팀은 실시간 토큰이나 TMDB의 제한에 대한 실제 요청 없이 포스터 그리드를 구축할 수 있습니다.

속도 제한 및 귀속 규칙

아래 내용은 TMDB 문서에서 인용되었습니다.

속도 제한. TMDB의 속도 제한 페이지에 따르면, 10초당 40회 요청이라는 원래 제한은 2019년 12월 16일에 비활성화되었습니다. 그러나 "불필요하게 높은 대량 스크래핑을 완화하기 위해" 상한선은 여전히 존재하며, "초당 약 40회 요청 범위"에 있습니다. 이 수치는 사전 통보 없이 변경될 수 있으므로, HTTP 429 오류가 발생하면 요청을 중단하고 다시 시도하세요.

비용. FAQ에서: "저희 API는 데이터 및/또는 이미지의 출처로 TMDB를 명시하는 한 비상업적 목적으로 무료로 사용할 수 있습니다." 상업적 프로젝트는 sales@themoviedb.org로 연락해야 합니다.

귀속. 애플리케이션에 TMDB 로고와 다음 문구를 표시하세요: "이 제품은 TMDB API를 사용하지만 TMDB의 보증이나 인증을 받지 않았습니다." API 이용 약관은 약간 더 긴 문구를 사용하며, 로고가 자체 브랜드보다 덜 두드러지게 표시되어야 하며, 색을 변경하거나, 늘리거나, 뒤집거나, 회전시켜서는 안 됩니다.

캐싱. 약관은 TMDB 데이터를 6개월 이상 캐싱하는 것을 금지합니다. 필요한 것을 저장하되, 새로고침 계획을 세우세요.

SLA 없음. TMDB는 명확히 밝히고 있습니다. 타임아웃과 재시도 로직을 구축하세요.

키 위생. 두 자격 증명 모두 환경 변수나 비밀 관리자에 보관해야 하며, 소스 코드에 직접 넣지 마세요. 만약 리포지토리에 노출되었다면, 설정 페이지에서 교체하고 전체 기록에 대해 API 키 유출 검사를 실행하세요.

일반적인 오류 및 그 의미

TMDB는 HTTP 상태와 함께 status_code 및 status_message를 포함하는 JSON 본문을 반환합니다. 오류 참조에는 수십 가지 코드가 나열되어 있으며, 이들은 먼저 보게 될 오류들입니다.

HTTP	status_code	메시지	일반적인 원인 및 해결 방법
401	7	잘못된 API 키: 유효한 키가 부여되어야 합니다.	잘못된 자격 증명 또는 잘못된 위치. v3 키는 `api_key`에, 읽기 액세스 토큰은 Bearer 헤더에 들어가야 하며, 반대로 사용해서는 안 됩니다. 뒤에 공백이 있는지 확인하세요.
401	3	인증 실패: 서비스에 접근할 권한이 없습니다.	잘못된 자격 증명 또는 누락된 헤더. `Authorization: Bearer <token>`으로 정확히 입력되었는지 확인하고, Bearer와 토큰 사이에 공백이 하나 있는지 확인하세요.
401	32	이메일 미인증: 이메일 주소가 인증되지 않았습니다.	TMDB 이메일을 인증한 후 다시 시도하세요. 새 키는 필요하지 않습니다.
404	34	요청한 리소스를 찾을 수 없습니다.	잘못된 ID 또는 경로 오타. `/3/movies/550`이 아니라 `/3/movie/550`입니다.
429	25	요청 횟수(#)가 허용된 한도(40)를 초과했습니다.	최대 요청량을 초과했습니다. 대기 후 백오프 방식으로 재시도하고, `append_to_response`를 사용하여 일괄 조회를 수행하세요.

자주 묻는 질문

TMDB API 키는 무료인가요?

네, TMDB를 출처로 표기하는 비상업적 용도로는 무료입니다. 유료 셀프 서비스 등급은 없습니다. 프로젝트에서 수익이 발생하는 경우, TMDB는 영업팀을 통해 상업적 계약을 체결하도록 요청합니다.

API 키를 사용해야 하나요, 아니면 읽기 액세스 토큰을 사용해야 하나요?

읽기 액세스 토큰을 Bearer 헤더로 사용하세요. TMDB는 이를 기본값으로 권장하며, v3와 v4 모두에서 작동하고, URL에 노출되지 않습니다. v3 키는 쿼리 파라미터만 전송할 수 있는 도구를 위해 존재합니다. 이 개념이 생소하다면, API 키란 무엇인가에 대한 이 입문서가 TMDB가 따르는 모델을 설명해 줄 것입니다.

브라우저나 모바일 앱에서 TMDB를 직접 호출할 수 있나요?

가능하지만, 클라이언트에 전송되는 모든 것은 토큰을 포함하여 공개됩니다. 개인 프로젝트의 경우 이는 용인되는 위험입니다. 사용자가 있는 모든 프로젝트의 경우, TMDB 앞에 작은 백엔드 또는 서버리스 함수를 두어 토큰을 보호하고 인기 있는 쿼리를 캐시하세요.

v3와 v4의 차이점은 무엇인가요?

v3는 카탈로그입니다: 검색, 영화 및 TV 상세 정보, 인물, 이미지, 탐색. v4는 목록, 즐겨찾기, 평점, 시청 목록과 같은 계정 기능을 다루며, 쓰기 엔드포인트에는 사용자 액세스 토큰이 필요합니다. 읽기 액세스 토큰은 두 API 모두에 대해 인증됩니다.

다음 단계

이제 작동하는 TMDB API 키, 어떤 자격 증명을 보내야 하는지에 대한 규칙, curl 및 Python에서의 검색-상세 정보 흐름, 그리고 Apidog 테스트 시나리오로 저장된 동일한 흐름을 갖게 되었습니다. 다음으로, 필터링된 탐색을 위해 discover/movie를 추가하고, 앱을 공유하기 전에 귀속 공지사항을 넣으세요. 카탈로그의 다른 모든 항목은 동일한 기본 URL, Bearer 헤더 및 오류 형식을 사용합니다.