The Movie Database (TMDB) là một danh mục phim, chương trình TV, dàn diễn viên và tác phẩm nghệ thuật do cộng đồng xây dựng. API của nó miễn phí cho mục đích phi thương mại miễn là bạn ghi công TMDB, điều này khiến nó trở thành điểm khởi đầu thông thường trong bất kỳ danh sách API phim miễn phí nào. Vấn đề nằm ở khâu giới thiệu: TMDB cung cấp cho bạn hai loại thông tin xác thực khác nhau và hướng dẫn bắt đầu chính thức giả định bạn đã biết nên sử dụng loại nào.
Hướng dẫn này bao gồm toàn bộ lộ trình: tài khoản, yêu cầu khóa, khóa v3 so với mã thông báo truy cập đọc v4, các lệnh gọi tìm kiếm và chi tiết đầu tiên trong curl và Python, các lệnh gọi tương tự được lưu dưới dạng thử nghiệm trong Apidog, cùng với giới hạn tốc độ, quy tắc ghi công và các lỗi bạn sẽ gặp ngay từ ngày đầu tiên.
Những gì bạn cần trước khi bắt đầu
- Một tài khoản TMDB với địa chỉ email đã được xác minh. API sẽ từ chối các tài khoản chưa xác minh bằng mã lỗi 401.
- Một trình duyệt máy tính để bàn. Tài liệu của TMDB cho biết các trang đăng ký API không được tối ưu hóa cho thiết bị di động.
- curl, hoặc Python 3 với gói
requests. - Apidog, để lưu trữ mã thông báo an toàn và giữ các yêu cầu. Tải Apidog cho macOS, Windows hoặc Linux.
Bước 1: tạo tài khoản TMDB
Truy cập themoviedb.org, nhấp vào “Join TMDB” (Tham gia TMDB), và đăng ký bằng địa chỉ email. Mở email xác minh và xác nhận trước khi bạn điều chỉnh cài đặt API. Bỏ qua bước này và sau đó bạn sẽ gặp lỗi 401 khó hiểu, mã trạng thái 32: “Email not verified: Your email address has not been verified.” (Email chưa được xác minh: Địa chỉ email của bạn chưa được xác minh).
Bước 2: yêu cầu khóa API
Sau khi đăng nhập, hãy mở cài đặt tài khoản của bạn và nhấp vào “API” trong thanh bên trái. FAQ của TMDB mô tả đây là cách duy nhất: “Bạn có thể đăng ký khóa API bằng cách nhấp vào liên kết ‘API’ từ thanh bên trái trong trang cài đặt tài khoản của bạn.”
Bạn sẽ chấp nhận các điều khoản sử dụng API, sau đó điền vào một đơn đăng ký ngắn: bạn đang xây dựng gì, một URL nếu có, tóm tắt cách bạn sẽ sử dụng dữ liệu và loại hình sử dụng. Chọn tùy chọn nhà phát triển cho các dự án cá nhân, bản thử nghiệm (prototype) và công cụ nội bộ. TMDB coi một dự án là thương mại “nếu mục đích chính là tạo ra doanh thu vì lợi ích của chủ sở hữu,” và con đường đó yêu cầu một thỏa thuận bằng văn bản với đội ngũ bán hàng của họ.
Sau khi bạn gửi, trang cài đặt tương tự sẽ hiển thị hai thông tin xác thực:
- Khóa API (API Key), được dán nhãn cho xác thực v3. Một chuỗi thập lục phân gồm 32 ký tự.
- Mã thông báo truy cập đọc API (API Read Access Token), một chuỗi kiểu JWT dài hơn nhiều.
TMDB không công bố lịch trình xem xét; trên thực tế, cả hai giá trị sẽ xuất hiện ngay sau khi biểu mẫu được gửi. Hãy coi chúng như bất kỳ bí mật nào khác và không để chúng xuất hiện trong các cam kết mã (commits), cửa sổ trò chuyện và ảnh chụp màn hình.
Khóa API v3 so với Mã thông báo truy cập đọc v4
Hai thông tin xác thực này không phải là “cũ” và “mới.” Chúng là hai cách để xác định cùng một ứng dụng, và tài liệu xác thực chính thức nêu rõ rằng cả hai đều “cung cấp cùng cấp độ truy cập.”
| Khóa API (v3) | Mã thông báo truy cập đọc API | |
|---|---|---|
| Cách bạn gửi | Tham số truy vấn: ?api_key=YOUR_KEY |
Header: Authorization: Bearer YOUR_TOKEN |
| Hoạt động với | Các endpoint v3 trong /3/ |
Các endpoint v3 và v4 |
| Mặc định của TMDB | Không | Có |
| Hiển thị trong nhật ký máy chủ và lịch sử trình duyệt | Có, nó nằm trong URL | Không |
Khuyến nghị của chính TMDB là mã thông báo Bearer: “Phương thức mặc định để xác thực là bằng mã thông báo truy cập của bạn,” và nó “có lợi ích bổ sung là một quy trình xác thực duy nhất mà bạn có thể sử dụng trên cả phương thức v3 và v4.”
Sử dụng header Bearer trừ khi ứng dụng khách của bạn không thể đặt header. Việc giữ thông tin xác thực ra khỏi URL là lập luận tương tự đằng sau bất kỳ quyết định nào về khóa API so với mã thông báo Bearer: URL bị ghi nhật ký, lưu vào bộ nhớ cache và chia sẻ.
Một điểm khác biệt nữa. Mọi thứ trong bài viết này là dữ liệu danh mục chỉ đọc, chỉ cần thông tin xác thực ứng dụng. API v4 bổ sung các tính năng tài khoản như danh sách, mục yêu thích, xếp hạng và danh sách xem. Ghi vào các tính năng đó cho người dùng TMDB cần một quá trình giao tiếp bổ sung: một mã thông báo yêu cầu từ /4/auth/request_token, sự chấp thuận của người dùng, sau đó là mã thông báo truy cập người dùng từ /4/auth/access_token. Không có điều nào trong số đó là cần thiết để tìm kiếm phim hoặc đọc chi tiết.
Bước 3: thực hiện yêu cầu đầu tiên của bạn
Tất cả các lệnh gọi v3 đều đến https://api.themoviedb.org/3. Hai endpoint bao gồm hầu hết các dự án đầu tiên: tìm kiếm theo tiêu đề, sau đó lấy chi tiết theo ID.
Tìm kiếm phim bằng 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'
Phản hồi là một đối tượng trang với page, results, total_pages và total_results. Mỗi kết quả chứa id, title, release_date, overview, poster_path, genre_ids và vote_average. Trong ví dụ tìm kiếm của TMDB, kết quả đầu tiên cho "fight club" là id 550, phát hành ngày 15-10-1999.
Lệnh gọi tương tự với khóa v3 trông như thế này. Lưu ý hoàn toàn không có header xác thực:
curl 'https://api.themoviedb.org/3/search/movie?query=fight%20club&api_key=YOUR_API_KEY'
Lấy chi tiết phim bằng Python
Bây giờ hãy lấy ID từ kết quả tìm kiếm và yêu cầu bản ghi đầy đủ. Endpoint chi tiết phim trả về runtime, genres, budget, revenue và overview. Tham số append_to_response của nó bổ sung các tài nguyên phụ như danh đề (credits) vào cùng một vòng truy vấn, tối đa 20 tài nguyên mỗi yêu cầu.
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"])
Dòng cuối cùng là phần mà mọi người thường bỏ sót. poster_path chỉ là một đường dẫn. Như hướng dẫn cơ bản về hình ảnh giải thích, một URL hợp lệ là https://image.tmdb.org/t/p/, sau đó là kích thước như w500 hoặc original, rồi đến đường dẫn. /3/configuration liệt kê mọi kích thước hợp lệ.
Bước 4: chạy và lưu các yêu cầu trong Apidog
Khi các lệnh gọi cơ bản hoạt động, hãy chuyển chúng đến nơi bạn sẽ không làm mất chúng. Trong Apidog, việc này chỉ mất vài phút và bạn sẽ có một bài kiểm tra đã lưu, có thể chia sẻ được.
- Tạo một dự án và thêm một môi trường có tên “TMDB” với hai biến:
base_urlđược đặt thànhhttps://api.themoviedb.org/3, vàtmdb_tokenchứa mã thông báo truy cập đọc của bạn. Đánh dấu mã thông báo là bí mật để nó bị che trong giao diện người dùng và không được xuất ra; hướng dẫn về biến môi trường và biến bí mật bao gồm các tùy chọn. - Thêm một yêu cầu GET đến
{{base_url}}/search/movievới tham sốquery. Trên tab Auth, chọn Bearer Token và nhập{{tmdb_token}}. Gửi nó và xác nhận bạn nhận được mã 200 và một mảngresults. - Thêm một yêu cầu GET thứ hai đến
{{base_url}}/movie/{{movie_id}}. Trong bộ xử lý hậu kỳ của yêu cầu đầu tiên, trích xuấtresults[0].idvàomovie_idđể lệnh gọi thứ hai luôn theo sau lệnh gọi đầu tiên. - Lưu cả hai dưới dạng một kịch bản thử nghiệm với các xác nhận: trạng thái bằng 200,
total_resultslớn hơn 0, vàtitletrong phản hồi chi tiết không rỗng. Chạy nó bất cứ khi nào tích hợp thay đổi.
Đang xây dựng giao diện người dùng dựa trên dữ liệu này? Bật máy chủ mô phỏng cho endpoint tìm kiếm. Apidog tạo ra một phản hồi khớp với lược đồ, vì vậy nhóm UI có thể xây dựng lưới poster mà không cần mã thông báo trực tiếp hoặc các yêu cầu thực tế chống lại giới hạn của TMDB.
Giới hạn tốc độ và quy tắc ghi công
Mọi thứ dưới đây được trích dẫn từ tài liệu của TMDB.
Giới hạn tốc độ. Trang giới hạn tốc độ của TMDB cho biết giới hạn ban đầu là 40 yêu cầu mỗi 10 giây đã bị vô hiệu hóa vào ngày 16 tháng 12 năm 2019. Các giới hạn trên vẫn còn “để giúp giảm thiểu việc thu thập dữ liệu hàng loạt không cần thiết,” và chúng “nằm trong khoảng 40 yêu cầu mỗi giây.” Con số đó có thể thay đổi mà không cần thông báo trước, vì vậy hãy tuân thủ bất kỳ lỗi HTTP 429 nào, chờ đợi và thử lại.
Chi phí. Từ FAQ: “API của chúng tôi miễn phí sử dụng cho các mục đích phi thương mại miễn là bạn ghi công TMDB là nguồn dữ liệu và/hoặc hình ảnh.” Các dự án thương mại phải liên hệ sales@themoviedb.org.
Ghi công. Hiển thị logo TMDB và thông báo này trong ứng dụng của bạn: “Sản phẩm này sử dụng API của TMDB nhưng không được TMDB xác nhận hoặc chứng nhận.” Các điều khoản sử dụng API sử dụng ngôn ngữ hơi dài hơn và yêu cầu logo phải ít nổi bật hơn thương hiệu của riêng bạn, và không bao giờ được đổi màu, kéo giãn, lật hoặc xoay.
Bộ nhớ đệm (Caching). Các điều khoản cấm lưu trữ bất kỳ dữ liệu TMDB nào trong bộ nhớ đệm quá sáu tháng. Lưu trữ những gì bạn cần, nhưng hãy lên kế hoạch làm mới.
Không có SLA. TMDB tuyên bố rõ ràng như vậy. Xây dựng các cơ chế hết thời gian chờ và thử lại.
Bảo mật khóa. Cả hai thông tin xác thực đều thuộc về các biến môi trường hoặc trình quản lý bí mật, không bao giờ nằm trong mã nguồn. Nếu một khóa nào đó xuất hiện trong kho lưu trữ (repo), hãy xoay vòng khóa đó từ trang cài đặt và chạy kiểm tra rò rỉ khóa API trên toàn bộ lịch sử của bạn.
Các lỗi thường gặp và ý nghĩa của chúng
TMDB trả về một body JSON với status_code và status_message cùng với trạng thái HTTP. Tài liệu tham khảo lỗi liệt kê hàng chục mã lỗi; đây là những lỗi bạn sẽ thấy đầu tiên.
| HTTP | status_code | Thông báo | Nguyên nhân và cách khắc phục thông thường |
|---|---|---|---|
| 401 | 7 | Invalid API key: You must be granted a valid key. (Khóa API không hợp lệ: Bạn phải được cấp một khóa hợp lệ.) | Thông tin xác thực sai hoặc đặt sai vị trí. Khóa v3 nằm trong api_key, mã thông báo truy cập đọc nằm trong header Bearer, không bao giờ ngược lại. Kiểm tra xem có dấu cách thừa ở cuối không. |
| 401 | 3 | Authentication failed: You do not have permissions to access the service. (Xác thực thất bại: Bạn không có quyền truy cập dịch vụ.) | Thông tin xác thực bị lỗi định dạng hoặc thiếu header. Xác nhận rằng nó có dạng Authorization: Bearer <token> với một dấu cách duy nhất. |
| 401 | 32 | Email not verified: Your email address has not been verified. (Email chưa được xác minh: Địa chỉ email của bạn chưa được xác minh.) | Xác minh email TMDB của bạn, sau đó thử lại. Không cần khóa mới. |
| 404 | 34 | The resource you requested could not be found. (Không tìm thấy tài nguyên bạn yêu cầu.) | ID sai hoặc lỗi chính tả trong đường dẫn. Nó phải là /3/movie/550, không phải /3/movies/550. |
| 429 | 25 | Your request count (#) is over the allowed limit of (40). (Số lượng yêu cầu của bạn (#) vượt quá giới hạn cho phép (40).) | Đã vượt quá giới hạn đột biến (burst ceiling). Chờ và thử lại với chế độ lùi lại (backoff); tra cứu hàng loạt bằng append_to_response. |
Câu hỏi thường gặp
Khóa API của TMDB có miễn phí không?
Có, cho mục đích phi thương mại với việc ghi công. Không có gói dịch vụ trả phí tự động. Nếu dự án của bạn tạo ra doanh thu, TMDB yêu cầu bạn sắp xếp một thỏa thuận thương mại thông qua đội ngũ bán hàng của họ.
Tôi nên sử dụng khóa API hay mã thông báo truy cập đọc?
Hãy sử dụng mã thông báo truy cập đọc dưới dạng header Bearer. TMDB gọi đây là mặc định, nó hoạt động trên cả v3 và v4, và nó không xuất hiện trong URL của bạn. Khóa v3 tồn tại cho các công cụ chỉ có thể gửi tham số truy vấn. Nếu khái niệm này còn mới, bài giới thiệu về khóa API là gì sẽ giải thích mô hình mà TMDB tuân theo.
Tôi có thể gọi trực tiếp TMDB từ trình duyệt hoặc ứng dụng di động không?
Bạn có thể, nhưng bất cứ thứ gì được gửi đến ứng dụng khách đều là công khai, bao gồm cả mã thông báo của bạn. Đối với một dự án cá nhân, đó là một rủi ro được chấp nhận. Đối với bất kỳ thứ gì có người dùng, hãy đặt một phần mềm backend nhỏ hoặc hàm serverless ở phía trước TMDB, giữ mã thông báo ở đó và lưu trữ các truy vấn phổ biến vào bộ nhớ đệm.
Sự khác biệt giữa v3 và v4 là gì?
v3 là danh mục: tìm kiếm, chi tiết phim và chương trình TV, người, hình ảnh, khám phá. v4 bao gồm các tính năng tài khoản như danh sách, mục yêu thích, xếp hạng và danh sách xem, và các endpoint ghi của nó yêu cầu mã thông báo truy cập người dùng. Mã thông báo truy cập đọc của bạn xác thực cho cả hai phiên bản.
Những việc cần làm tiếp theo
Bây giờ bạn đã có một khóa API TMDB hoạt động, một quy tắc về thông tin xác thực cần gửi, một quy trình tìm kiếm-sau-đó-xem-chi-tiết trong curl và Python, và quy trình tương tự được lưu dưới dạng kịch bản thử nghiệm Apidog. Tiếp theo, hãy thêm discover/movie để duyệt tìm kiếm có bộ lọc và đặt thông báo ghi công vào ứng dụng của bạn trước khi chia sẻ. Mọi thứ khác trong danh mục đều sử dụng cùng URL cơ sở, header Bearer và cấu trúc lỗi.