Khóa API của Perplexity là thông tin xác thực bạn gửi kèm theo mỗi yêu cầu tới api.perplexity.ai. Nó dùng để nhận diện dự án của bạn, trừ vào số dư tín dụng trả trước và thiết lập cấp độ giới hạn tốc độ của bạn. Nếu bạn chưa từng xử lý khóa API trước đây, bài giới thiệu của chúng tôi về khóa API là gì sẽ trình bày những kiến thức cơ bản. Hướng dẫn này bao gồm phần dành riêng cho Perplexity: tạo tài khoản, nạp tín dụng, tạo khóa và gửi yêu cầu Sonar có tham chiếu đầu tiên của bạn từ curl, Python và Apidog.
Một lưu ý về thời gian trước khi bạn bắt đầu. Perplexity đã chuyển Sonar sang Agent API của họ, và hướng dẫn bắt đầu nhanh chính thức hiện nay cũng chỉ tới đó. Điểm cuối chat-completions Sonar cũ vẫn sẽ hoạt động cho đến ngày 27 tháng 9 năm 2026, sau đó sẽ ngừng hoạt động. Mọi ví dụ dưới đây đều sử dụng điểm cuối hiện tại, kèm theo một ghi chú ngắn về định dạng cũ trong trường hợp bạn đang bảo trì mã nguồn cũ.
Những gì bạn cần trước khi bắt đầu
- Một tài khoản Perplexity. Bạn có thể sử dụng Google, Apple, SSO hoặc đăng nhập qua email không mật khẩu, tất cả đều sẽ dẫn đến cùng một tài khoản bằng địa chỉ email.
- Một thẻ thanh toán. API là hình thức trả tiền theo mức sử dụng mà không cần đăng ký gói, nhưng các yêu cầu sẽ thất bại ngay khi số dư tín dụng của bạn bằng không.
- curl hoặc Python 3.9+ cho yêu cầu đầu tiên.
- Apidog nếu bạn muốn khóa được lưu trữ dưới dạng bí mật cục bộ và yêu cầu được lưu dưới dạng thử nghiệm có thể lặp lại.
Bước 1: Đăng nhập vào bảng điều khiển API và tạo dự án
Truy cập console.perplexity.ai và chọn một phương thức đăng nhập. Đăng nhập sẽ tạo một tài khoản Perplexity, nhưng không tạo dự án API. Trong lần truy cập đầu tiên, trình hướng dẫn thiết lập sẽ nhắc bạn tạo hoặc tham gia một dự án trước khi bạn có thể tạo khóa, vì các khóa được giới hạn trong phạm vi dự án.
Mở mục Cài đặt ở thanh bên trái và điền tên tổ chức, địa chỉ và thông tin thuế của bạn; những thông tin này sẽ xuất hiện trên hóa đơn của bạn. Nếu công ty bạn đã có dự án, hãy yêu cầu quản trị viên thêm bạn vào dự án đó thay vì tạo một dự án thứ hai. Các dự án riêng biệt sẽ có số dư tín dụng và khóa riêng biệt, điều này hữu ích để tách biệt một ứng dụng sản phẩm khỏi một thử nghiệm.
Bước 2: Thêm phương thức thanh toán và tín dụng
Mở trang Thanh toán và thêm thẻ. Theo tài liệu, việc thêm phương thức thanh toán không tính phí thẻ; nó chỉ lưu trữ thông tin chi tiết để sử dụng trong tương lai. Sau đó mua tín dụng. Số dư, chi tiết sử dụng theo từng mô hình và lịch sử hóa đơn đều có trên trang này.
Có hai chi tiết quan trọng ở đây. API tính phí từ tín dụng trả trước, và nếu số dư hết, khóa của bạn sẽ bị chặn cho đến khi bạn nạp thêm. Tài liệu mô tả lỗi này là 401, không phải 402, vì vậy một ứng dụng hết tín dụng thoạt nhìn sẽ giống như một lỗi xác thực. Và bên cạnh mục Tự động nạp lại, hãy nhấp vào Thay đổi tùy chọn để bảng điều khiển tự động thêm tín dụng khi số dư giảm xuống dưới ngưỡng bạn đặt. Bật tính năng này trước khi đưa bất kỳ thứ gì vào sản xuất.
Tài liệu không công bố số tiền mua tối thiểu, vì vậy hãy dựa vào những gì trang thanh toán hiển thị cho bạn. Cấp độ sử dụng của bạn, quyết định giới hạn tốc độ, dựa trên tổng số tín dụng đã mua trong suốt thời gian tồn tại của tài khoản, chứ không phải dựa trên số dư hiện tại.
Bước 3: Tạo khóa API
Mở trang Khóa API trong bảng điều khiển và tạo một khóa. Đặt cho nó một cái tên mô tả như dev-laptop hoặc prod-search-worker. Sau khi tạo, tên là cách duy nhất để phân biệt các khóa, vì giá trị đầy đủ chỉ được hiển thị một lần và không thể lấy lại được. Hãy sao chép nó ngay lập tức.
Đặt khóa vào một biến môi trường, không bao giờ để trong mã nguồn:
export PERPLEXITY_API_KEY="pplx-your-key-here"
Trên Windows, sử dụng setx PERPLEXITY_API_KEY "pplx-your-key-here" và mở một terminal mới.
Bạn có thể tạo nhiều khóa trong một dự án, vì vậy hãy tạo một khóa cho mỗi môi trường và mỗi dịch vụ. Thu hồi một khóa là vĩnh viễn, đây là điều bạn muốn khi một khóa bị lộ. Nếu bạn không chắc liệu một khóa đã bị lộ vào kho lưu trữ hay chưa, hãy chạy trình quét bí mật trên lịch sử git của bạn trước khi bạn xoay vòng khóa.
Bước 4: Thực hiện yêu cầu Sonar đầu tiên của bạn
Điểm cuối hiện tại là POST https://api.perplexity.ai/v1/agent. Xác thực là một tiêu đề bearer chuẩn, Authorization: Bearer $PERPLEXITY_API_KEY. Phần thân yêu cầu (body) chứa một model và một chuỗi input. ID mô hình Sonar trên điểm cuối này là perplexity/sonar, và việc thêm công cụ web_search cho nó biết cách tìm kiếm trên web trực tiếp và đính kèm các nguồn.
Hãy hỏi nó một câu hỏi có câu trả lời thực tế thay đổi theo thời gian:
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "perplexity/sonar",
"input": "Which Node.js release line is currently Active LTS, and when does it reach end of life?",
"tools": [{ "type": "web_search" }]
}' | jq
Phản hồi mang theo output_text, câu trả lời dưới dạng văn bản thuần, và một mảng output với mỗi mục tương ứng với một bước mà mô hình đã thực hiện. Mục message chứa câu trả lời; mục search_results liệt kê các trang nó đã đọc, mỗi trang có url, title, snippet và date. Đối tượng usage báo cáo số lượng token và chi phí. Một status là completed có nghĩa là quá trình chạy đã hoàn tất.
Yêu cầu tương tự trong Python với SDK chính thức:
pip install perplexityai
from perplexity import Perplexity
client = Perplexity() # reads PERPLEXITY_API_KEY from the environment
response = client.responses.create(
model="perplexity/sonar",
input="Which Node.js release line is currently Active LTS, and when does it reach end of life?",
tools=[{"type": "web_search"}],
)
print(response.output_text)
Nếu bạn thích OpenAI SDK, hãy đặt base_url="https://api.perplexity.ai/v1" và gọi client.responses.create() với các đối số tương tự. SDK sẽ định tuyến nó đến /v1/responses, mà Perplexity chấp nhận như một bí danh. Các cài đặt sẵn (fast, low, medium, high, xhigh) kết hợp một mô hình, ngân sách token và công cụ cho bạn; trên OpenAI SDK, bạn truyền chúng qua extra_body.
Nếu bạn đang sử dụng định dạng chat-completions cũ
Mã nguồn cũ gửi messages tới https://api.perplexity.ai/v1/sonar với các ID mô hình sonar, sonar-pro, sonar-reasoning-pro, hoặc sonar-deep-research, và đọc choices[0].message.content. Định dạng đó hoạt động cho đến ngày 27 tháng 9 năm 2026. Hướng dẫn di chuyển ánh xạ sonar sang perplexity/sonar, sonar-pro sang perplexity/sonar với cài đặt sẵn low, và nghiên cứu sâu sang cài đặt sẵn high. Các tùy chọn search_domain_filter và search_recency_filter được chuyển vào bên trong công cụ web_search dưới dạng đối tượng filters.
Bước 5: Lưu trữ khóa và lưu yêu cầu trong Apidog
Một lệnh curl chỉ hoạt động một lần không phải là một thử nghiệm. Dưới đây là cách thiết lập chúng tôi sử dụng trong Apidog để khóa không nằm trên đám mây và yêu cầu chạy theo yêu cầu.
Tạo một môi trường. Thêm một môi trường có tên Perplexity với hai biến: base_url được đặt là https://api.perplexity.ai dưới dạng giá trị chia sẻ, và PERPLEXITY_API_KEY với giá trị chia sẻ để trống làm chỗ giữ chỗ và khóa thực sự chỉ nằm trong giá trị cục bộ. Các giá trị cục bộ tồn tại trong bộ nhớ cache của máy khách của bạn và không bao giờ đồng bộ hóa với đồng đội, đó là mục đích chính. Hướng dẫn của chúng tôi về môi trường và biến bí mật trong Apidog đi sâu hơn vào sự phân tách giữa chia sẻ và cục bộ.
Xây dựng yêu cầu. Yêu cầu mới, POST {{base_url}}/v1/agent. Thêm tiêu đề Authorization: Bearer {{PERPLEXITY_API_KEY}}, đặt loại thân yêu cầu (body type) là JSON, và dán cùng nội dung thân yêu cầu như lệnh curl ở trên. Chọn môi trường Perplexity và nhấp Gửi. Bạn sẽ thấy output_text và khối search_results trong bảng phản hồi.
Biến nó thành một thử nghiệm. Thêm ba khẳng định: mã trạng thái là 200, $.status bằng completed, và $.output_text không trống. Lưu yêu cầu vào một kịch bản thử nghiệm. Giờ đây, bất kỳ ai trong nhóm cũng có thể kéo dự án, dán khóa của riêng họ vào giá trị cục bộ và xác minh thiết lập của họ chỉ bằng một cú nhấp chuột. Xoay vòng khóa nghĩa là chỉnh sửa một trường, chứ không phải tìm kiếm trong các script.
Nếu bạn chưa có, hãy Tải xuống Apidog miễn phí; gói miễn phí hỗ trợ bốn người dùng, đủ cho một nhóm nhỏ cùng chia sẻ dự án.
Giới hạn tốc độ và chi phí yêu cầu
Giới hạn tốc độ trên Agent API thay đổi theo cấp độ sử dụng của bạn, và các cấp độ được thiết lập dựa trên tổng số tín dụng đã mua trong suốt thời gian tồn tại của tài khoản, theo trang giới hạn tốc độ:
| Cấp độ | Tín dụng đã mua | Yêu cầu mỗi giây | Yêu cầu mỗi phút |
|---|---|---|---|
| 0 | $0 | 1 | 50 |
| 1 | $50+ | 3 | 150 |
| 2 | $250+ | 8 | 500 |
| 3 | $500+ | 17 | 1.000 |
| 4 | $1.000+ | 33 | 4.000 |
| 5 | $5.000+ | 33 | 8.000 |
Giới hạn sử dụng thuật toán "leaky-bucket" (xô rò rỉ), vì vậy các đợt tăng đột biến ngắn hạn lên đến giới hạn sẽ được thông qua. Khi bạn vượt quá giới hạn, API sẽ trả về 429 với tiêu đề Retry-After, và các yêu cầu bị từ chối sẽ không bị tính phí. Cấp độ hiện tại của bạn hiển thị trên trang Giá của bảng điều khiển dưới tab cấp độ sử dụng.
Về giá cả, một đoạn văn ở đây là đủ. Trang giá liệt kê perplexity/sonar trên Agent API với giá 0,25 đô la cho mỗi triệu token đầu vào và 2,50 đô la cho mỗi triệu token đầu ra, cộng thêm 0,0025 đô la cho mỗi lần gọi web_search. Các mô hình chat-completions Sonar cũ tính phí khác nhau: sonar với giá 1 đô la cho mỗi triệu token vào và ra, cộng thêm 5 đến 12 đô la cho mỗi nghìn yêu cầu tùy thuộc vào kích thước ngữ cảnh tìm kiếm. Để biết chi tiết đầy đủ và góc độ tài khoản Pro, hãy xem hướng dẫn API Perplexity của chúng tôi.
Các lỗi thường gặp và cách khắc phục
401 Unauthorized (Không được ủy quyền). Ba nguyên nhân, theo thứ tự khả năng xảy ra: tiêu đề sai (nó phải là Authorization: Bearer <key>, và biến shell phải được xuất trong cùng một terminal), khóa đã bị thu hồi, hoặc số dư tín dụng bằng không. Kiểm tra trang thanh toán trước khi bạn tạo lại bất cứ điều gì. Python SDK sẽ báo lỗi AuthenticationError cho trường hợp này.
400 Bad Request (Yêu cầu không hợp lệ). Thường là do gửi một phần thân yêu cầu (body) từ định dạng cũ đến điểm cuối mới: messages thay vì input, hoặc một ID mô hình sonar-pro trần trụi trên /v1/agent. SDK hiển thị lỗi này dưới dạng ValidationError.
404 Not Found (Không tìm thấy). Đường dẫn sai. /v1/agent là Agent API và /v1/sonar là điểm cuối chat-completions cũ; tài liệu không liệt kê bất kỳ cái nào khác.
429 Too Many Requests (Quá nhiều yêu cầu). Bạn đã đạt đến giới hạn cấp độ của mình. Đọc tiêu đề Retry-After, đợi khoảng thời gian đó, sau đó thử lại với chiến lược lùi lũy thừa và jitter. Mua thêm tín dụng sẽ nâng cấp cấp độ của bạn nếu bạn cần thông lượng liên tục. Hướng dẫn xử lý lỗi của SDK cho thấy mẫu RateLimitError.
500 hoặc 503. Lỗi phía máy chủ. Thử lại sau một khoảng thời gian chờ; các vòng lặp thử lại quá chặt chẽ sẽ làm cho việc giới hạn tốc độ trở nên tồi tệ hơn.
Câu hỏi thường gặp
Có khóa API Perplexity miễn phí không?
Không có cấp độ miễn phí nào được ghi nhận trong tài liệu. API hoạt động theo hình thức trả tiền theo mức sử dụng từ số dư tín dụng trả trước, và một dự án không có tín dụng sẽ bị chặn. Chi phí cho yêu cầu đầu tiên với perplexity/sonar và một tìm kiếm web chỉ là một phần nhỏ của một xu, vì vậy một khoản nạp nhỏ có thể hỗ trợ rất nhiều thử nghiệm.
Tôi nên sử dụng ID mô hình nào cho yêu cầu đầu tiên?
Sử dụng perplexity/sonar trên /v1/agent với công cụ web_search. Đây là tùy chọn có tham chiếu với chi phí thấp nhất và là tùy chọn mà hướng dẫn di chuyển ánh xạ các ID sonar và sonar-pro cũ sang. Chuyển sang một cài đặt sẵn như low hoặc medium khi bạn muốn Perplexity tự động chọn mô hình và ngân sách tìm kiếm cho bạn.
Tôi có cần Agent API nếu tôi chỉ muốn kết quả tìm kiếm không?
Không. API Tìm kiếm riêng biệt trả về các kết quả được xếp hạng mà không cần chạy mô hình, điều này rẻ hơn khi bạn đưa các trang vào quy trình xử lý của riêng mình. Hướng dẫn chi tiết của chúng tôi về API Tìm kiếm của Perplexity cho thấy cấu trúc yêu cầu và các bộ lọc.
Làm cách nào để xoay vòng khóa mà không gây gián đoạn?
Tạo một khóa thứ hai trong cùng một dự án, triển khai nó ở mọi nơi khóa cũ đã được sử dụng, xác nhận lưu lượng truy cập trên khóa mới, sau đó thu hồi khóa cũ. Việc thu hồi là vĩnh viễn, vì vậy hãy cập nhật mọi người dùng trước. Perplexity cũng cung cấp các điểm cuối /generate_auth_token và /revoke_auth_token nếu bạn muốn tự động hóa quá trình xoay vòng.
Tổng kết
Đăng nhập, tạo dự án, mua tín dụng, tạo khóa, gửi một yêu cầu tới /v1/agent với perplexity/sonar. Đó là toàn bộ quá trình. Lưu khóa dưới dạng giá trị cục bộ trong Apidog và lưu yêu cầu dưới dạng một thử nghiệm, và người tiếp theo trong nhóm của bạn sẽ có một thiết lập có thể xác minh được trong vài phút. Nếu bạn vẫn có mã nguồn trên điểm cuối chat-completions, hãy di chuyển nó trước ngày 27 tháng 9 năm 2026.