Perplexity API 설정 가이드: API 키 생성부터 Python·Node.js 자동화까지

Perplexity API 완벽 설정 가이드

Perplexity API는 실시간 웹 검색 기반 AI 응답을 제공하는 강력한 도구입니다. 이 가이드에서는 API 키 생성부터 Python과 Node.js 프로젝트에 통합하는 전체 워크플로우를 단계별로 안내합니다.

1단계: API 키 생성

• perplexity.ai에 로그인합니다.- 좌측 하단 프로필 아이콘 → Settings를 클릭합니다.- API 탭으로 이동합니다.- Generate API Key 버튼을 클릭합니다.- 생성된 키를 안전한 곳에 즉시 복사합니다. (키는 한 번만 표시됩니다.)- 결제 정보를 등록하고 크레딧을 충전합니다. API는 사용량 기반 과금입니다.⚠️ 중요: API 키는 환경 변수로 관리하고 코드에 직접 포함하지 마세요.

2단계: Sonar 모델 선택

Perplexity API는 Sonar 모델 계열을 제공합니다. 용도에 따라 적절한 모델을 선택하세요.

설치

pip install openai requests

환경 변수 설정

# Linux/macOS
export PERPLEXITY_API_KEY="YOUR_API_KEY"

# Windows PowerShell
$env:PERPLEXITY_API_KEY="YOUR_API_KEY"

기본 리서치 자동화 코드

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("PERPLEXITY_API_KEY"),
    base_url="https://api.perplexity.ai"
)

def research(query, model="sonar", recency=None, domains=None):
    """Perplexity API를 활용한 리서치 함수"""
    messages = [
        {"role": "system", "content": "정확한 출처와 함께 한국어로 답변하세요."},
        {"role": "user", "content": query}
    ]

    extra_body = {"return_citations": True}
    if recency:
        extra_body["search_recency_filter"] = recency
    if domains:
        extra_body["search_domain_filter"] = domains

    response = client.chat.completions.create(
        model=model,
        messages=messages,
        extra_body=extra_body
    )

    result = response.choices[0].message.content
    citations = getattr(response, "citations", [])
    return {"answer": result, "citations": citations}

# 사용 예시: 최근 1주일 기술 뉴스 조사
result = research(
    query="2026년 최신 LLM 트렌드를 정리해줘",
    model="sonar-pro",
    recency="week"
)
print(result["answer"])
for i, url in enumerate(result["citations"], 1):
    print(f"[{i}] {url}")

배치 리서치 자동화

import json
import time

def batch_research(topics, output_file="research_results.json"):
    """여러 주제를 순차적으로 조사하여 JSON으로 저장"""
    results = []
    for topic in topics:
        print(f"조사 중: {topic}")
        data = research(topic, model="sonar-pro")
        results.append({"topic": topic, **data})
        time.sleep(1)  # Rate limit 방지

    with open(output_file, "w", encoding="utf-8") as f:
        json.dump(results, f, ensure_ascii=False, indent=2)
    print(f"{len(results)}건 저장 완료: {output_file}")

topics = ["AI 에이전트 프레임워크 비교", "RAG 최신 기법", "LLM 파인튜닝 비용"]
batch_research(topics)

5단계: Node.js 통합

설치

npm install openai

리서치 자동화 코드

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PERPLEXITY_API_KEY,
  baseURL: "https://api.perplexity.ai",
});

async function research(query, options = {}) {
  const { model = "sonar", recency = null, domains = null } = options;

  const body = {
    model,
    messages: [
      { role: "system", content: "정확한 출처와 함께 한국어로 답변하세요." },
      { role: "user", content: query },
    ],
    return_citations: true,
  };

  if (recency) body.search_recency_filter = recency;
  if (domains) body.search_domain_filter = domains;

  const response = await client.chat.completions.create(body);

  return {
    answer: response.choices[0].message.content,
    citations: response.citations || [],
  };
}

// 사용 예시: 특정 도메인에서만 검색
const result = await research("Next.js 15 주요 변경사항", {
  model: "sonar-pro",
  recency: "month",
  domains: ["nextjs.org", "github.com"],
});

console.log(result.answer);
result.citations.forEach((url, i) => console.log(`[${i + 1}] ${url}`));

Pro Tips: 파워 유저를 위한 팁

• 시스템 프롬프트 활용: system 메시지에 출력 형식(JSON, 마크다운 테이블 등)을 지정하면 후처리가 쉬워집니다.- 도메인 필터 조합: search_domain_filter에 학술 사이트(arxiv.org, scholar.google.com)만 지정하면 학술 리서치 품질이 크게 향상됩니다.- 스트리밍 응답: stream: true 파라미터로 실시간 스트리밍이 가능합니다. 긴 응답의 UX가 개선됩니다.- 비용 최적화: 단순 팩트 체크는 sonar, 심층 분석은 sonar-pro를 사용하여 비용을 절감하세요.- 멀티턴 대화: messages 배열에 이전 대화를 포함하면 후속 질문이 컨텍스트를 유지합니다.

Troubleshooting: 자주 발생하는 오류

Q1. Perplexity API와 OpenAI API의 가장 큰 차이점은 무엇인가요?

Perplexity API는 실시간 웹 검색 결과를 기반으로 응답을 생성합니다. OpenAI API는 학습 데이터 기반 응답인 반면, Perplexity는 최신 정보와 출처 URL을 함께 반환하므로 리서치 자동화에 특화되어 있습니다. OpenAI SDK 호환 인터페이스를 사용하므로 기존 코드에서 base_url만 변경하면 됩니다.

Q2. Perplexity API 요금 체계는 어떻게 되나요?

Perplexity API는 토큰 기반 종량제입니다. 모델별로 입력·출력 토큰당 요금이 다르며, sonar가 가장 경제적이고 sonar-pro와 sonar-deep-research는 더 높은 요금이 적용됩니다. 월별 사용량은 Settings → API → Usage에서 확인할 수 있으며, 사전에 크레딧을 충전해야 합니다.

Q3. search_domain_filter와 search_recency_filter를 동시에 사용할 수 있나요?

네, 두 파라미터를 동시에 사용하면 특정 도메인 내에서 특정 기간의 콘텐츠만 검색할 수 있습니다. 예를 들어 search_domain_filter: [“github.com”]과 search_recency_filter: “week”을 함께 지정하면 지난 1주일 내 GitHub 콘텐츠만 참조하여 응답합니다. 이는 최신 오픈소스 프로젝트 동향 파악에 매우 유용합니다.