Perplexity API 설치 및 설정 완전 가이드 – pplx-api 키 발급부터 Python 연동까지
Perplexity API란?
Perplexity API는 실시간 웹 검색 결과를 기반으로 답변을 생성하는 AI 검색 강화 API입니다. OpenAI 호환 형식을 사용하므로 기존 LLM 워크플로에 쉽게 통합할 수 있으며, 각 응답에 출처(citation)가 포함되어 팩트체킹이 가능한 AI 애플리케이션을 구축할 수 있습니다.
1단계: API 키 발급
- Perplexity 계정 생성 —
perplexity.ai에 접속하여 회원가입 또는 로그인합니다.- API 설정 페이지 이동 — 로그인 후perplexity.ai/settings/api로 이동합니다.- 크레딧 충전 — API 사용을 위해 최소 $5 이상의 크레딧을 충전합니다. Pro 구독과 API 크레딧은 별도로 관리됩니다.- 키 생성 — “Generate API Key” 버튼을 클릭하면pplx-로 시작하는 API 키가 발급됩니다. 이 키는 한 번만 표시되므로 즉시 안전한 곳에 저장하세요.
2단계: 개발 환경 설정
Python 패키지 설치
Perplexity API는 OpenAI SDK와 호환됩니다. 별도의 전용 SDK 없이 openai 패키지를 사용합니다.
pip install openai
환경 변수 설정
API 키를 코드에 직접 하드코딩하지 말고 환경 변수로 관리하세요.
# Linux / macOS
export PERPLEXITY_API_KEY="pplx-YOUR_API_KEY"
Windows PowerShell
$env:PERPLEXITY_API_KEY=“pplx-YOUR_API_KEY”
.env 파일 사용 (권장)
echo “PERPLEXITY_API_KEY=pplx-YOUR_API_KEY” > .env
pip install python-dotenv
3단계: 첫 번째 API 호출
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("PERPLEXITY_API_KEY"),
base_url="https://api.perplexity.ai"
)
response = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "system", "content": "You are a helpful research assistant. Answer in Korean."},
{"role": "user", "content": "2026년 AI 에이전트 시장 동향을 알려줘"}
]
)
print(response.choices[0].message.content)4단계: 소스 인용(Citation) 파싱
Perplexity API의 가장 큰 장점은 각 응답에 출처 URL이 포함된다는 점입니다. 인용 정보는 응답 객체의 citations 필드에 배열로 반환됩니다.
import json
response = client.chat.completions.create(
model=“sonar-pro”,
messages=[
{“role”: “user”, “content”: “한국의 2026년 반도체 수출 전망은?”}
]
)
응답 본문 출력
answer = response.choices[0].message.content
print(“답변:”, answer)
인용 소스 파싱
citations = getattr(response, ‘citations’, [])
if citations:
print(“\n📚 참고 출처:”)
for i, url in enumerate(citations, 1):
print(f” [{i}] {url}“)
인용 정보를 HTML로 렌더링하기
def format_citations_html(citations):
if not citations:
return ""
html = "
#### 참고 출처
"
for url in citations:
html += f"- {url}"
html += ""
return html5단계: 검색 강화 모델 선택
Perplexity는 용도에 따라 다양한 모델을 제공합니다. 올바른 모델을 선택하면 비용과 성능을 최적화할 수 있습니다.
| 모델 | 특징 | 추천 용도 | 입력 토큰 비용 |
|---|---|---|---|
sonar | 빠른 응답, 기본 검색 | 간단한 질의, 챗봇 | $1 / 1M tokens |
sonar-pro | 심층 검색, 멀티스텝 추론 | 리서치, 복잡한 분석 | $3 / 1M tokens |
sonar-reasoning | 추론 체인 포함, 단계별 사고 | 기술 분석, 의사결정 지원 | $3 / 1M tokens |
sonar-reasoning-pro | 고급 추론 + 검색 결합 | 전문 리서치, 보고서 생성 | $5 / 1M tokens |
response = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "system", "content": "기술 리서치 전문가로 답변하세요."},
{"role": "user", "content": "RAG vs Fine-tuning 비교 분석"}
],
temperature=0.2, # 낮을수록 정확한 답변
max_tokens=2048, # 최대 응답 길이
top_p=0.9, # 핵 샘플링
search_recency_filter="week", # 최근 1주일 결과만
return_related_questions=True # 관련 질문 반환
)
### search_recency_filter 옵션
- hour — 최근 1시간 내 결과- day — 최근 24시간 내 결과- week — 최근 1주일 내 결과- month — 최근 1개월 내 결과
## 7단계: 스트리밍 응답 구현
stream = client.chat.completions.create( model="sonar", messages=[ {"role": "user", "content": "Python 비동기 프로그래밍 핵심 개념"} ], stream=True )
for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True)
Pro Tips — 파워 유저를 위한 고급 팁
- 시스템 프롬프트 최적화 — 시스템 메시지에 “반드시 한국어로 답변하고, 출처를 명시하라”고 지시하면 일관된 한국어 응답을 받을 수 있습니다.- 비용 관리 — 간단한 질문에는
sonar, 심층 리서치에만sonar-pro를 사용하여 비용을 절감하세요. API 대시보드에서 일일 사용량을 모니터링할 수 있습니다.- 재시도 로직 구현 — 429(Rate Limit) 오류 시 지수 백오프를 적용하세요:tenacity라이브러리의@retry(wait=wait_exponential(min=1, max=60))를 활용하면 편리합니다.- 컨텍스트 윈도우 관리 — sonar 모델은 최대 128K 토큰 컨텍스트를 지원합니다. 긴 대화에서는 이전 메시지를 요약하여 토큰을 절약하세요.- search_domain_filter — 특정 도메인만 검색 대상으로 지정하거나 제외할 수 있습니다. 신뢰할 수 있는 출처만 참조하고 싶을 때 유용합니다.
Troubleshooting — 자주 발생하는 오류 해결
| 오류 | 원인 | 해결 방법 |
|---|---|---|
401 Unauthorized | 잘못된 API 키 또는 만료 | API 키가 pplx-로 시작하는지 확인. 설정 페이지에서 키 재발급 |
402 Payment Required | 크레딧 부족 | API 대시보드에서 크레딧 잔액 확인 후 충전 |
429 Too Many Requests | 속도 제한 초과 | 요청 간격을 늘리거나 지수 백오프 적용 |
model not found | 잘못된 모델명 | 최신 모델 목록 확인 — sonar, sonar-pro 등 정확한 이름 사용 |
| 빈 citations 배열 | 검색 결과 없음 또는 모델 특성 | sonar-pro 모델 사용 시 인용이 더 풍부하게 반환됨 |
**디버깅 팁:** 응답 객체 전체를 확인하려면 다음과 같이 출력하세요.
import json
print(json.dumps(response.model_dump(), indent=2, ensure_ascii=False))
## 자주 묻는 질문 (FAQ)
Q1: Perplexity API는 무료로 사용할 수 있나요?
Perplexity API는 종량제(pay-per-use) 방식으로 운영됩니다. 무료 크레딧이 제공되지 않으며, 최소 $5 이상 충전 후 사용할 수 있습니다. Perplexity Pro 구독은 웹 인터페이스용이며 API 크레딧과는 별도입니다. 모델별로 입력·출력 토큰 비용이 다르므로, 용도에 맞는 모델을 선택하여 비용을 관리하세요.
Q2: OpenAI SDK 대신 REST API를 직접 호출할 수 있나요?
네, 가능합니다. Perplexity API는 표준 REST 엔드포인트(https://api.perplexity.ai/chat/completions)를 제공합니다. curl이나 requests 라이브러리로 직접 호출할 수 있으며, 요청·응답 형식은 OpenAI Chat Completions API와 동일합니다. 다만 OpenAI SDK를 사용하면 스트리밍, 에러 핸들링 등이 자동으로 처리되어 더 편리합니다.
Q3: 한국어 질의 시 영어로 답변이 오는 경우 어떻게 하나요?
시스템 메시지에 언어를 명시적으로 지정하세요. 예를 들어 {“role”: “system”, “content”: “항상 한국어로 답변하세요.”}를 추가하면 됩니다. 또한 사용자 메시지 자체를 한국어로 작성하면 한국어 응답 확률이 높아집니다. sonar-pro 모델이 다국어 지원에서 더 안정적인 성능을 보입니다.