Perplexity Router API

Perplexity Router API

Router API는 Perplexity가 호스팅하는 오픈웨이트 모델들을 하나의 통합 API와 하나의 API 키로 접근하게 해 주는 서비스예요. OpenAI Chat Completions·OpenAI Responses·Anthropic Messages 형식으로 요청을 보내면, 사용자가 제공사별 계정·SDK·장애 조치 로직을 관리하지 않아도 플랫폼이 각 요청을 정상 배포로 자동 라우팅해 줘요.

출처: Perplexity Router API Quickstart

⚠️ Router API는 현재 private preview 상태예요. 사용 권한을 얻으려면 [email protected]로 요청해야 합니다.

개요

Router API는 하나의 API와 하나의 키로 오픈웨이트 모델 접근을 통합해요. 카탈로그의 어떤 모델이든——원래 제공사가 누구든——지원하는 스키마 어느 것으로도 호출할 수 있어요. 이 특성 덕분에 Router는 기존 OpenAI·Anthropic 통합의 drop-in 대체재가 돼요. base URL과 API 키만 바꾸면 되거든요.

직접 모델에 접근해서 자체 프롬프트와 툴을 쓰려면 Router API를, 내장 인용이 있는 웹 근거 답변이 필요하면 Agent API를 쓰는 게 좋아요.

Base URL은 https://api.perplexity.ai/router/v1이고, 기존 Perplexity API 키가 그대로 동작해요.

설치와 인증

Router API는 OpenAI Chat Completions·Responses 형식과 Anthropic Messages 형식을 지원하므로, 각 제공사의 공식 SDK를 쓰면 돼요.

  • Python: pip install openai (Chat Completions·Responses), pip install anthropic (Messages)
  • TypeScript: npm install openai, npm install @anthropic-ai/sdk

인증은 PERPLEXITY_API_KEY 환경 변수로 설정해요. 요청은 Authorization: Bearer 헤더로 인증되며 SDK가 api_key 파라미터에서 자동으로 설정해 줘요.

기본 사용

OpenAI SDK를 Router base URL로 가리키고 카탈로그의 모델 id를 넘기면 돼요. 모델 id는 creator/model-name 슬러그 형식이라 제공사 전환이 한 줄 변경으로 끝나요.

from openai import OpenAI
import os

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

response = client.chat.completions.create(
    model="perplexity/kimi-k3",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "CAP 정리를 두 문장으로 설명해 주세요."}
    ]
)
print(response.choices[0].message.content)

응답은 요청한 모델 id를 그대로 반영하고, 요청이 어떻게 처리됐든 항상 그 모델의 게시된 요금으로 청구돼요.

OpenAI Responses 형식

OpenAI Responses 통합을 쓰는 곳이라면 같은 base URL로 client.responses.create()를 호출하면 돼요. Router Responses 엔드포인트는 stateless라서 매 요청에 전체 대화를 input에 담아 보내야 해요.

response = client.responses.create(
    model="perplexity/kimi-k3",
    input="CAP 정리를 두 문장으로 설명해 주세요.",
    max_output_tokens=1024
)
print(response.output_text)

스트리밍

stream: true로 설정하면 토큰을 server-sent events로 받아요. 스트리밍 응답에서 토큰 사용량까지 보려면 stream_options: {"include_usage": true}도 함께 설정하면, data: [DONE] 직전 마지막 청크로 사용량이 도착해요.

stream = client.chat.completions.create(
    model="perplexity/kimi-k3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "네트워크 지연에 관한 하이쿠를 써 주세요."}],
    stream=True,
    stream_options={"include_usage": True}
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Anthropic Messages 형식

같은 모델을 Anthropic Messages 형식으로 /router/v1/messages에서 호출할 수 있어요. Anthropic SDK에 맞춰 쓰던 코드는 base URL만 바꾸면 동작해요. 단, Anthropic SDK는 base URL 뒤에 /v1/messages를 붙이므로 https://api.perplexity.ai/router(끝에 /v1 없이)로 설정하는 점을 주의하세요.

from anthropic import Anthropic
import os

client = Anthropic(
    api_key=os.environ.get("PERPLEXITY_API_KEY"),
    base_url="https://api.perplexity.ai/router"
)
message = client.messages.create(
    model="perplexity/kimi-k3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "CAP 정리를 두 문장으로 설명해 주세요."}]
)
print(message.content[0].text)

모델 목록 확인

GET https://api.perplexity.ai/router/v1/models를 호출하면 현재 카탈로그를 언제든 조회할 수 있어요. 응답은 OpenAI 호환이고 모델 id 기준으로 정렬되며, 각 모델의 1M 토큰당 기본 가격(USD)이 함께 들어 있어요.

curl 'https://api.perplexity.ai/router/v1/models' \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" | jq

더 알아보기