Perplexity API 키 발급받고 첫 Sonar 요청 보내는 방법

Perplexity API 키는 `api.perplexity.ai`로 보내는 모든 요청과 함께 전송하는 자격 증명입니다. 이 키는 프로젝트를 식별하고, 선불 크레딧 잔액에서 차감하며, 요금 제한 등급을 설정합니다. API 키를 한 번도 다뤄본 적이 없다면, API 키란 무엇인가에 대한 기본 지침서를 참조하세요. 이 가이드는 Perplexity에 특화된 부분, 즉 계정 생성, 크레딧 추가, 키 생성, 그리고 curl, Python, Apidog에서 첫 번째 Sonar 요청을 보내는 방법을 다룹니다.

시작하기 전에 한 가지 시점에 대한 참고 사항이 있습니다. Perplexity는 Sonar를 Agent API로 이전했으며, 공식 퀵스타트는 이제 해당 API를 가리킵니다. 기존 Sonar 채팅 완성(chat-completions) 엔드포인트는 2026년 9월 27일까지 작동하며 그 이후에는 중단됩니다. 아래의 모든 예시는 현재 엔드포인트를 사용하며, 이전 코드를 유지 관리하는 경우를 대비하여 레거시 형식에 대한 간략한 설명이 포함되어 있습니다.

button

시작하기 전에 필요한 것

Perplexity 계정. Google, Apple, SSO 또는 비밀번호 없는 이메일 로그인이 모두 작동하며, 이들은 이메일 주소를 통해 동일한 계정으로 연결됩니다.
결제 카드. API는 구독 없이 종량제(pay-as-you-go) 방식이지만, 크레딧 잔액이 0이 되면 요청이 실패합니다.
첫 번째 요청을 위한 curl 또는 Python 3.9 이상.
키를 로컬 비밀 정보로 저장하고 요청을 반복 가능한 테스트로 저장하려면 Apidog.

1단계: API 콘솔에 로그인하고 프로젝트 생성

console.perplexity.ai로 이동하여 로그인 방법을 선택하세요. 로그인하면 Perplexity 계정이 생성되지만, API 프로젝트는 생성되지 않습니다. 처음 방문할 때 설정 마법사가 키를 생성하기 전에 프로젝트를 생성하거나 가입하도록 안내합니다. 키는 프로젝트에 한정되기 때문입니다.

왼쪽 사이드바에서 설정을 열고 조직의 이름, 주소 및 세금 정보를 입력하세요. 이 정보는 청구서에 표시됩니다. 회사에 이미 프로젝트가 있는 경우, 관리자에게 요청하여 새로운 프로젝트를 만드는 대신 기존 프로젝트에 추가해 달라고 요청하세요. 별도의 프로젝트는 별도의 크레딧 잔액과 키를 가지므로, 프로덕션 앱을 실험 환경과 분리하는 데 유용합니다.

2단계: 결제 수단 및 크레딧 추가

청구 페이지를 열고 카드를 추가하세요. 문서에 따르면, 결제 수단을 추가하는 것은 카드에 청구하는 것이 아니라 향후 사용을 위한 정보를 저장하는 것입니다. 그런 다음 크레딧을 구매하세요. 잔액, 모델별 사용량 세부 정보, 청구서 내역은 모두 이 페이지에 있습니다.

여기서 두 가지 중요한 세부 사항이 있습니다. API는 선불 크레딧에서 청구되며, 잔액이 소진되면 충전할 때까지 키가 차단됩니다. 문서는 이러한 실패를 402가 아닌 401로 설명하므로, 크레딧이 부족한 앱은 언뜻 보기에 인증 버그처럼 보입니다. 그리고 자동 재충전 옆에 있는 환경설정 변경을 클릭하여 잔액이 설정한 임계값 아래로 떨어질 때 콘솔이 자동으로 크레딧을 추가하도록 설정하세요. 프로덕션 환경에 배포하기 전에 이 기능을 켜두세요.

문서에는 최소 구매 금액이 명시되어 있지 않으므로, 청구 페이지에 표시된 내용을 따르세요. 사용량 등급은 현재 잔액이 아닌 계정 수명 동안 누적 구매한 크레딧을 기준으로 요금 제한을 설정합니다.

3단계: API 키 생성

콘솔의 API 키 페이지를 열고 키를 생성하세요. `dev-laptop` 또는 `prod-search-worker`와 같이 설명적인 이름을 지정하세요. 생성 후에는 전체 값이 한 번만 표시되고 다시 검색할 수 없으므로, 이름이 키를 구별하는 유일한 방법입니다. 즉시 복사하세요.

키를 환경 변수에 저장하고, 코드에는 절대 넣지 마세요:

export PERPLEXITY_API_KEY="pplx-your-key-here"

Windows에서는 `setx PERPLEXITY_API_KEY "pplx-your-key-here"`를 사용하고 새 터미널을 여세요.

하나의 프로젝트 내에서 여러 개의 키를 생성할 수 있으므로, 환경 및 서비스별로 하나씩 만드세요. 키를 취소하는 것은 영구적이므로, 키가 유출되었을 때 원하는 조치입니다. 키가 이미 저장소로 유출되었는지 확실하지 않다면, 키를 교체하기 전에 git 기록에 대해 비밀 스캐너를 실행하세요.

4단계: 첫 번째 Sonar 요청 보내기

현재 엔드포인트는 `POST https://api.perplexity.ai/v1/agent`입니다. 인증은 표준 베어러 헤더인 `Authorization: Bearer $PERPLEXITY_API_KEY`입니다. 본문은 `model`과 `input` 문자열을 받습니다. 이 엔드포인트의 Sonar 모델 ID는 `perplexity/sonar`이며, `web_search` 도구를 추가하면 실시간 웹을 검색하고 출처를 첨부하도록 지시합니다.

시간이 지남에 따라 변하는 실제 답변이 있는 것을 물어보세요:

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

응답에는 `output_text`(일반 텍스트 형식의 답변)와 모델이 수행한 각 단계별 항목이 하나씩 있는 `output` 배열이 포함됩니다. `message` 항목은 답변을 담고 있으며, `search_results` 항목은 읽은 페이지 목록을 제공하며 각 페이지는 `url`, `title`, `snippet`, `date`를 포함합니다. `usage` 객체는 토큰 수와 비용을 보고합니다. `status`가 `completed`는 실행이 완료되었음을 의미합니다.

공식 SDK를 사용한 Python에서의 동일한 요청:

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)

OpenAI SDK를 선호하는 경우, `base_url="https://api.perplexity.ai/v1"`로 설정하고 동일한 인수로 `client.responses.create()`를 호출하세요. SDK는 이를 `/v1/responses`로 라우팅하며, Perplexity는 이를 별칭으로 허용합니다. 프리셋(`fast`, `low`, `medium`, `high`, `xhigh`)은 모델, 토큰 예산 및 도구를 함께 제공합니다. OpenAI SDK에서는 `extra_body`를 통해 전달합니다.

레거시 채팅 완성(chat-completions) 형식을 사용하는 경우

기존 코드는 모델 ID `sonar`, `sonar-pro`, `sonar-reasoning-pro` 또는 `sonar-deep-research`와 함께 `messages`를 `https://api.perplexity.ai/v1/sonar`로 보내고 `choices[0].message.content`를 읽습니다. 해당 형식은 2026년 9월 27일까지 작동합니다. 마이그레이션 가이드는 `sonar`를 `perplexity/sonar`로, `sonar-pro`를 `low` 프리셋이 적용된 `perplexity/sonar`로, 심층 연구(deep research)를 `high` 프리셋으로 매핑합니다. `search_domain_filter` 및 `search_recency_filter` 옵션은 `filters` 객체로 `web_search` 도구 내부로 이동합니다.

5단계: Apidog에 키 저장 및 요청 저장

한 번만 작동하는 curl은 테스트가 아닙니다. 키가 클라우드에 저장되지 않고 요청이 필요할 때 실행되도록 Apidog에서 사용하는 설정입니다.

환경 생성. `Perplexity`라는 환경을 만들고 두 개의 변수를 추가합니다: 공유 값으로 `https://api.perplexity.ai`로 설정된 `base_url`과, 공유 값은 플레이스홀더로 남겨두고 실제 키는 로컬 값에만 넣은 `PERPLEXITY_API_KEY`입니다. 로컬 값은 클라이언트의 캐시에 저장되며 팀원에게 동기화되지 않습니다. 이것이 핵심입니다. Apidog의 환경 및 비밀 변수에 대한 가이드는 공유 값과 로컬 값의 분리에 대해 더 자세히 설명합니다.

요청 생성. 새 요청, `POST {{base_url}}/v1/agent`. `Authorization: Bearer {{PERPLEXITY_API_KEY}}` 헤더를 추가하고, 본문 유형을 JSON으로 설정한 다음, 위 curl과 동일한 본문을 붙여넣습니다. `Perplexity` 환경을 선택하고 보내기(Send)를 클릭합니다. 응답 패널에서 `output_text`와 `search_results` 블록을 볼 수 있을 것입니다.

테스트로 전환. 세 가지 어설션(assertion)을 추가합니다: 상태 코드는 `200`, `$.status`는 `completed`와 같고, `$.output_text`는 비어 있지 않습니다. 요청을 테스트 시나리오에 저장합니다. 이제 팀의 누구나 프로젝트를 가져와 로컬 값에 자신의 키를 붙여넣고 한 번의 클릭으로 설정을 확인할 수 있습니다. 키를 교체하는 것은 스크립트를 뒤적거리는 것이 아니라 하나의 필드를 편집하는 것을 의미합니다.

아직 Apidog가 없다면 무료로 다운로드하세요. 무료 플랜은 4명의 사용자를 지원하며, 소규모 팀이 프로젝트를 공유하기에 충분합니다.

요금 제한 및 요청 비용

Agent API의 요금 제한은 사용량 등급에 따라 달라지며, 등급은 요금 제한 페이지에 따라 평생 크레딧 구매액에 의해 설정됩니다:

등급	구매 크레딧	초당 요청 수	분당 요청 수
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

제한은 리키 버킷(leaky-bucket) 알고리즘을 사용하므로, 제한까지의 짧은 버스트는 통과됩니다. 초과하면 API는 `Retry-After` 헤더와 함께 `429`를 반환하며, 거부된 요청은 청구되지 않습니다. 현재 등급은 콘솔의 가격 페이지(Pricing page)에 있는 사용량 등급(usage tiers) 탭에 표시됩니다.

가격 책정에 대해서는 여기 한 단락으로 충분합니다. 가격 페이지에 따르면 Agent API의 `perplexity/sonar`는 100만 입력 토큰당 $0.25, 100만 출력 토큰당 $2.50이며, `web_search` 호출당 $0.0025가 추가됩니다. 레거시 Sonar 채팅 완성 모델은 다르게 청구됩니다: `sonar`는 입출력 토큰 100만 개당 $1이며, 검색 컨텍스트 크기에 따라 요청 1천 개당 $5~$12가 추가됩니다. 전체 세부 정보 및 Pro 계정 관점은 Perplexity API 가이드를 참조하세요.

일반적인 오류 및 해결 방법

401 Unauthorized (인증되지 않음). 발생 가능성이 높은 순서대로 세 가지 원인이 있습니다: 헤더가 잘못됨 (`Authorization: Bearer`여야 하며, 셸 변수가 동일한 터미널에서 export되어야 함), 키가 취소되었거나, 크레딧 잔액이 0입니다. 어떤 것을 다시 생성하기 전에 청구 페이지를 확인하세요. Python SDK는 이 경우 `AuthenticationError`를 발생시킵니다.
400 Bad Request (잘못된 요청). 일반적으로 새 엔드포인트로 전송된 이전 형식의 본문입니다: `input` 대신 `messages` 또는 `/v1/agent`에서 bare `sonar-pro` 모델 ID를 사용하는 경우입니다. SDK는 이를 `ValidationError`로 표시합니다.
404 Not Found (찾을 수 없음). 경로가 잘못되었습니다. `/v1/agent`는 Agent API이고 `/v1/sonar`는 레거시 채팅 완성 엔드포인트입니다. 문서에는 다른 것이 나열되어 있지 않습니다.
429 Too Many Requests (요청 과다). 등급의 제한에 도달했습니다. `Retry-After`를 읽고, 해당 시간만큼 기다린 다음, 지수 백오프(exponential backoff) 및 지터(jitter)로 재시도하세요. 지속적인 처리량이 필요한 경우 크레딧을 구매하면 등급이 올라갑니다. SDK의 오류 처리 가이드는 `RateLimitError` 패턴을 보여줍니다.
500 또는 503. 서버 측 오류입니다. 지연 후 재시도하세요. 너무 짧은 재시도 루프는 요금 제한을 악화시킵니다.

자주 묻는 질문

무료 Perplexity API 키가 있나요?

문서화된 무료 등급은 없습니다. API는 선불 크레딧 잔액에서 종량제 방식으로 운영되며, 크레딧이 없는 프로젝트는 차단됩니다. `perplexity/sonar`와 한 번의 웹 검색을 포함하는 첫 번째 요청 비용은 1센트 미만이므로, 소액 충전으로 많은 테스트를 할 수 있습니다.

첫 번째 요청에는 어떤 모델 ID를 사용해야 하나요?

`web_search` 도구와 함께 `/v1/agent`에서 `perplexity/sonar`를 사용하세요. 이것은 가장 저렴한 기반 옵션이며, 마이그레이션 가이드가 기존 `sonar` 및 `sonar-pro` ID를 매핑하는 대상입니다. Perplexity가 모델과 검색 예산을 자동으로 선택하도록 하려면 `low` 또는 `medium`과 같은 프리셋으로 전환하세요.

검색 결과만 원하면 Agent API가 필요한가요?

아니요. 별도의 검색 API는 모델을 실행하지 않고 순위가 매겨진 결과를 반환하므로, 페이지를 자체 파이프라인에 공급할 때 더 저렴합니다. Perplexity 검색 API에 대한 가이드에서 요청 형식과 필터를 확인할 수 있습니다.

다운타임 없이 키를 교체하려면 어떻게 해야 하나요?

동일한 프로젝트에서 두 번째 키를 생성하고, 이전 키가 사용되던 모든 곳에 새 키를 배포하고, 새 키의 트래픽을 확인한 다음, 이전 키를 취소하세요. 취소는 영구적이므로, 모든 소비자(사용자)를 먼저 업데이트해야 합니다. Perplexity는 키 교체를 스크립트로 작성하려는 경우 `/generate_auth_token` 및 `/revoke_auth_token` 엔드포인트도 노출합니다.

마무리

로그인하고, 프로젝트를 생성하고, 크레딧을 구매하고, 키를 생성한 다음, `perplexity/sonar`와 함께 `/v1/agent`로 하나의 요청을 보내세요. 이것이 전체 과정입니다. Apidog에 키를 로컬 값으로 저장하고 요청을 테스트로 저장하면, 팀의 다음 사람이 몇 분 안에 검증 가능한 설정을 얻을 수 있습니다. 채팅 완성(chat-completions) 엔드포인트에 코드가 남아 있다면, 2026년 9월 27일 이전에 마이그레이션하세요.