Perplexity API 설치 및 설정 완전 가이드 – pplx-api 키 발급부터 Python SDK 연동까지
Perplexity API란?
Perplexity API는 실시간 웹 검색 기능이 내장된 대규모 언어 모델(LLM) API입니다. OpenAI 호환 인터페이스를 제공하므로 기존 코드베이스에 쉽게 통합할 수 있으며, 검색 강화 생성(Search-Augmented Generation) 기능을 통해 최신 정보가 포함된 응답과 출처 인용을 자동으로 제공합니다.
1단계: API 키 발급
- perplexity.ai에 접속하여 계정을 생성하거나 로그인합니다.- 좌측 메뉴에서 Settings → API로 이동합니다.- Generate API Key 버튼을 클릭합니다.- 생성된 키를 안전한 곳에 복사하여 저장합니다. 키는
pplx-로 시작합니다.- 결제 정보(Credit)를 등록합니다. Perplexity API는 사용량 기반 과금 방식입니다.
2단계: 개발 환경 설정
Python 패키지 설치
Perplexity API는 OpenAI SDK와 호환되므로 openai 패키지를 사용합니다.
pip install openai requests python-dotenv
환경 변수 설정
API 키를 코드에 직접 넣지 말고 .env 파일로 관리하세요.
# .env 파일 생성
PPLX_API_KEY=pplx-YOUR_API_KEY
# Python에서 환경 변수 로드 import os from dotenv import load_dotenv
load_dotenv() api_key = os.getenv(“PPLX_API_KEY”)
CLI에서 환경 변수 설정 (Linux/macOS)
export PPLX_API_KEY="pplx-YOUR_API_KEY"PowerShell (Windows)
$env:PPLX_API_KEY = "pplx-YOUR_API_KEY"3단계: 첫 번째 API 호출
OpenAI SDK를 이용한 기본 호출
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("PPLX_API_KEY"),
base_url="https://api.perplexity.ai"
)
response = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "system", "content": "정확하고 간결하게 답변하세요."},
{"role": "user", "content": "2026년 최신 Python 웹 프레임워크 트렌드를 알려줘"}
]
)
print(response.choices[0].message.content)requests 라이브러리를 이용한 직접 호출
import requests
import json
url = "https://api.perplexity.ai/chat/completions"
headers = {
"Authorization": f"Bearer {os.getenv('PPLX_API_KEY')}",
"Content-Type": "application/json"
}
payload = {
"model": "sonar-pro",
"messages": [
{"role": "user", "content": "서울 날씨 현재 상황"}
]
}
res = requests.post(url, headers=headers, json=payload)
data = res.json()
print(data["choices"][0]["message"]["content"])4단계: 소스 인용(Citation) 파싱
Perplexity API의 핵심 장점은 응답에 출처 URL이 포함된다는 점입니다. citations 필드를 통해 참조 소스를 추출할 수 있습니다.
response = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "user", "content": "한국의 2026년 AI 정책 동향"}
]
)
응답 본문
content = response.choices[0].message.content
print(“답변:”, content)
인용 소스 추출
citations = getattr(response, ‘citations’, [])
if citations:
print(“\n참조 소스:”)
for i, url in enumerate(citations, 1):
print(f” [{i}] {url}“)
인용 번호와 URL 매핑
응답 텍스트에 [1], [2] 형태로 삽입된 인용 번호는 citations 배열의 인덱스와 대응합니다. 이를 활용해 하이퍼링크로 변환할 수 있습니다.
import re
def replace_citations(text, citations):
"""인용 번호를 마크다운 링크로 변환"""
def replacer(match):
idx = int(match.group(1)) - 1
if 0 <= idx < len(citations):
return f”{match.group(1)}”
return match.group(0)
return re.sub(r’[(\d+)]’, replacer, text)
formatted = replace_citations(content, citations)
print(formatted)
5단계: 검색 강화 모드 및 모델 선택
| 모델 | 특징 | 용도 |
|---|---|---|
sonar | 빠른 응답, 기본 검색 | 간단한 질의, 실시간 정보 |
sonar-pro | 정밀 검색, 복합 추론 | 심층 분석, 리서치 |
sonar-reasoning | 다단계 추론, 체인 오브 씽킹 | 복잡한 논리 문제, 비교 분석 |
sonar-reasoning-pro | 최고 성능 추론 | 전문 연구, 고난이도 분석 |
response = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "user", "content": "최신 React 19 변경사항"}
],
search_domain_filter=["reactjs.org", "github.com", "developer.mozilla.org"],
search_recency_filter="week"
)stream = client.chat.completions.create( model="sonar-pro", messages=[{"role": "user", "content": "AI 에이전트 아키텍처 설명"}], stream=True )
for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True)
Pro Tips
- 시스템 프롬프트 활용:
system메시지에 응답 형식(JSON, 마크다운 등)과 언어를 명시하면 일관된 출력을 얻을 수 있습니다.- search_recency_filter:day,week,month,year옵션으로 최신 정보 범위를 제한하세요.- 토큰 비용 절약:sonar모델은sonar-pro대비 비용이 낮으므로 간단한 질의에는 기본 모델을 사용하세요.- temperature 조절: 사실 기반 검색에는temperature=0.1, 창의적 생성에는0.7이상을 권장합니다.- 대화 컨텍스트 유지:messages배열에 이전 대화를 포함하면 멀티턴 검색이 가능합니다.
Troubleshooting
| 에러 | 원인 | 해결 방법 |
|---|---|---|
401 Unauthorized | API 키 누락 또는 만료 | 키가 pplx-로 시작하는지 확인, 재발급 시도 |
429 Too Many Requests | 요청 속도 제한 초과 | 요청 간 딜레이 추가, time.sleep(1) 적용 |
400 Bad Request | 잘못된 모델명 또는 파라미터 | 모델명 확인: sonar, sonar-pro 등 공식 모델명 사용 |
credits 부족 | 계정 크레딧 소진 | Perplexity 대시보드에서 크레딧 충전 |
timeout | 복잡한 쿼리로 인한 응답 지연 | timeout=60 파라미터 추가, 쿼리 단순화 |
Q1: Perplexity API와 OpenAI API의 차이점은 무엇인가요?
Perplexity API는 실시간 웹 검색이 기본 내장되어 있어 별도의 검색 도구 없이 최신 정보를 포함한 응답을 생성합니다. 또한 응답에 출처 URL(citations)이 자동으로 포함되어 정보의 신뢰성을 검증할 수 있습니다. OpenAI API는 학습 데이터 기반으로 응답하며, 웹 검색을 위해서는 별도의 도구 연동이 필요합니다.
Q2: 무료로 Perplexity API를 사용할 수 있나요?
Perplexity API는 사용량 기반 유료 서비스입니다. 신규 가입 시 일정량의 무료 크레딧이 제공될 수 있으며, 이후에는 토큰 사용량에 따라 과금됩니다. 최신 가격 정책은 Perplexity 공식 문서를 확인하세요.
Q3: sonar와 sonar-pro 모델 중 어떤 것을 선택해야 하나요?
sonar 모델은 빠른 응답 속도와 낮은 비용이 장점이며 간단한 사실 확인이나 실시간 정보 조회에 적합합니다. sonar-pro는 더 깊은 검색과 복합적 추론이 필요한 리서치, 비교 분석, 심층 보고서 작성에 권장됩니다. 프로토타입 단계에서는 sonar로 시작하고, 품질이 부족하면 sonar-pro로 전환하는 전략이 효율적입니다.