저널 Uncategorized

퍼플렉시티 Orchestrator API 정리: 키 하나로 여러 AI 모델 호출, 요금·사용 등급과 장애 대응 방식

노트북에서 보낸 요청이 가운데 통합 관문을 거쳐 여러 서버로 나뉘고, 경고 표시가 뜬 서버 대신 같은 모양의 다른 서버로 우회하는 모습을 그린 AI 생성 설명 일러스트
AI로 생성한 설명용 일러스트이며 실제 사건의 사진이 아닙니다.

서비스에 AI 기능을 붙이다 보면 모델을 하나만 쓰기는 어렵습니다. 간단한 분류는 저렴한 모델에 맡기고 어려운 질문만 상위 모델로 보내고 싶은데, 그러려면 회사마다 계정과 API 키, 청구서를 따로 관리해야 합니다. 특정 제공업체에 장애가 나면 재시도 코드도 직접 짜야 합니다.

퍼플렉시티(Perplexity)가 11월 공개한 Orchestrator API는 이 부분을 한 API로 묶겠다는 개발자용 상품입니다. 아래에서는 공식 블로그와 개발자 문서를 기준으로 연결 방법, 요금과 사용 등급, 장애 대응과 자동 라우팅, 쓰기 전에 확인할 점을 정리했습니다. 직접 호출해 본 결과가 아니라 공개 문서 내용이라는 점을 먼저 밝혀 둡니다.

1. Orchestrator API는 무엇을 하는 상품인가

퍼플렉시티 설명에 따르면 Orchestrator는 OpenAI, Anthropic, Google, xAI의 모델과 GLM, Kimi, DeepSeek 같은 오픈웨이트 모델을 하나의 API와 하나의 청구 체계로 제공합니다. 오픈웨이트 모델은 퍼플렉시티 또는 추론 파트너가 운영합니다.

회사는 자사 서비스 안에서 이미 85개 이상 모델과 10곳이 넘는 제공업체로 요청을 나눠 보내고 있으며, 그 내부 계층을 외부 개발자에게 연 것이라고 설명합니다.

  • 요청 형식: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages 세 가지
  • 용도: 내가 만든 프롬프트와 도구로 모델을 직접 호출하는 용도
  • 구분: 웹 검색 근거와 인용이 붙은 답변은 별도 상품인 Agent API 영역

즉 퍼플렉시티 검색 답변을 받는 API가 아니라, 여러 회사 모델 앞에 세우는 일종의 통합 관문(게이트웨이)에 가깝습니다.

2. 연결 방법: API 키와 주소만 바꾸는 구조

퀵스타트 문서는 기존 OpenAI나 Anthropic SDK를 그대로 쓰고 기본 주소(base URL)와 키만 바꾸면 된다고 안내합니다. 주소는 SDK에 따라 조금 다릅니다.

  • OpenAI SDK·직접 HTTP 호출: https://api.perplexity.ai/orchestrator/v1
  • Anthropic SDK: https://api.perplexity.ai/orchestrator (끝에 /v1을 붙이지 않음)
  • 모델 이름: openai/gpt-6.1-sol, anthropic/claude-opus-5-5처럼 제작사/모델명 형식

같은 모델 ID를 세 가지 요청 형식 어디에서나 쓸 수 있어, 예를 들어 Anthropic 모델을 Chat Completions 형식으로 부르는 것도 가능하다고 문서는 설명합니다. 다만 Responses 형식은 상태를 저장하지 않으므로 매 요청에 대화 전체를 넣어야 하고, store나 previous_response_id 같은 필드는 오류로 거절됩니다.

호출 가능한 모델과 기본 단가는 /orchestrator/v1/models 목록 조회로 확인할 수 있습니다. 이 목록은 내 사용 등급에서 부를 수 있는 모델만 보여 줍니다.

3. 요금과 사용 등급: 처음부터 모든 모델을 부를 수는 없다

요금 문서에 따르면 과금은 모델별 공개 단가에 따른 토큰당 방식이고 요청당 수수료는 없습니다. 출시 글은 크레딧 위에 별도 플랫폼 수수료를 붙이지 않는다고 밝혔습니다. 사용량은 퍼플렉시티 API 콘솔의 선불 크레딧에서 차감되며, AWS Marketplace로도 크레딧을 살 수 있습니다.

모델·요금 표에서 확인한 100만 토큰당 단가 예시는 다음과 같습니다(미국 달러, 입력/출력).

  • anthropic/claude-opus-5-5: 4달러 / 20달러
  • openai/gpt-6.1-sol: 2달러 / 10달러(입력 27만2천 토큰 이하 기준)
  • openai/gpt-6-luna: 0.10달러 / 0.50달러(같은 기준)
  • perplexity/glm-5.3: 1.4달러 / 4.4달러

추론 토큰은 출력 단가로, 캐시 읽기는 별도 캐시 단가로 계산됩니다. Anthropic 모델과 일부 OpenAI 모델은 5분짜리 캐시 쓰기에 입력 단가의 1.25배가 붙습니다. OpenAI 모델에서만 쓸 수 있는 flex 등급은 0.5배, priority 등급은 2배입니다.

더 중요한 것은 사용 등급입니다. 등급 문서 기준으로 누적 크레딧 구매액에 따라 등급이 오르고, 모델마다 최소 등급이 정해져 있습니다.

  • Tier 0(구매 0달러): Google, xAI, 오픈웨이트 모델
  • Tier 1(누적 50달러 이상): OpenAI 모델과 대부분의 Anthropic 모델
  • Tier 2(누적 250달러 이상): Claude Opus 5·Opus 5.5·Fable 계열

등급이 모자라면 HTTP 402 오류가 납니다. 잔액이 아니라 누적 구매액 기준이라, 크레딧을 조금 충전한다고 상위 모델이 바로 열리지는 않습니다.

4. 장애 대응(페일오버): 모델은 그대로, 서버만 바꾼다

Orchestrator의 핵심 기능은 같은 모델 안에서의 자동 재시도입니다. 라우팅·안정성 문서에 따르면 한 모델이 여러 배포(제공처)에서 운영될 때, 한 곳에서 오류·속도 제한·시간 초과가 나면 같은 모델의 다른 배포로 요청을 다시 보냅니다. 퍼플렉시티는 Anthropic에서 실패한 Claude 요청이 AWS Bedrock에서 처리될 수 있다는 예를 들었습니다.

  • 잘못된 요청이나 문맥 길이 초과 같은 클라이언트 오류(400)는 재시도하지 않음
  • 모든 배포가 실패하면 429와 Retry-After 헤더를 반환하며, 출력 전에 실패한 요청은 과금하지 않음
  • 스트리밍이 시작된 뒤 끊기면 오류 이벤트로 끝나고, 실제 전달된 토큰만큼 과금
  • 어느 배포가 처리하든 요청한 모델의 단가로 계산

퍼플렉시티는 기술 블로그에서 2026년 10월 4일부터 11월 2일까지 자사를 거친 Claude·GPT 요청의 성공률이 측정한 개별 제공업체보다 높았다고 밝혔습니다. 다만 회사 자체 측정이고, MarkTechPost가 지적했듯 구체적인 성공률 수치는 공개되지 않았습니다. 사용자가 특정 배포를 직접 고를 수도 없습니다.

5. perplexity/auto 자동 라우팅(프리뷰)

프리뷰 기능인 자동 라우팅은 모델 이름에 perplexity/auto를 넣고, 기본 모델(default_model)과 경로(routes)를 적은 routing 객체를 함께 보내는 방식입니다. 각 경로에는 이름, 어떤 요청인지 설명하는 문장, 담당 모델을 적습니다.

요청이 오면 퍼플렉시티의 판단 모델이 대화를 읽고 경로 설명과 맞춰 봅니다. 이때 판단 모델은 모델 이름을 보지 않습니다. 맞는 경로가 없거나 판단 모델이 실패하면 기본 모델이 답합니다. 어떤 경로로 갔는지는 x-perplexity-autoroute-outcome, x-perplexity-autoroute-route 응답 헤더로 확인할 수 있습니다.

  • 회사가 든 고객지원 예: 일반 문의는 GLM-5.3 Flash, 결제 분쟁은 Claude Opus 5.5, 기술 장애는 GPT-6.1 Sol
  • 내장 프로필: Lower cost, Balanced, Higher quality 중 선택 가능
  • 대화 단위 캐시 유지: 같은 prompt_cache_key를 반복해 보내면 같은 배포에 머무르도록 돕는다고 안내

퍼플렉시티는 Terminal-Bench 4.1의 63개 과제로 조정 비교를 해 봤다고 밝혔습니다. Claude Fable 5.2만 쓸 때 38개를 풀었고, 보안·생명과학·거절 이후 요청을 GPT 모델로 넘기는 경로를 더하자 41개를 풀었습니다. 회사는 과제당 추정 비용이 더 높았다고 함께 적었습니다. 이 역시 자체 측정이며 작업 종류에 따라 결과가 달라질 수 있습니다.

6. 쓰기 전에 확인할 주의점

도입을 검토한다면 아래 항목을 먼저 확인하는 편이 안전합니다.

  • 접근 상태: 출시 글은 콘솔에서 키를 만들어 시작하라고 안내하지만, 확인 시점의 퀵스타트·라우팅 문서 상단에는 비공개 프리뷰(private preview)이며 이메일로 접근을 요청하라는 문구가 남아 있었습니다. 내 계정에서 실제로 호출되는지 콘솔에서 확인하세요.
  • 자체 키 사용 불가: FAQ에 따르면 OpenAI·Anthropic 등 다른 회사 API 키를 연결할 수 없습니다. 기존 직접 계약 조건을 그대로 쓰기 어렵다는 뜻입니다.
  • 데이터 보관: ZDR(무보관)은 기본적으로 꺼져 있고 서면 계약이 필요합니다. ZDR 조직에서는 Claude Fable 계열과 gpt-6.2-astra 호출이 403으로 막힙니다.
  • 비용 계산: 응답에는 비용 필드가 없고 토큰 수만 나옵니다. 캐시·추론 토큰을 단가표에 곱해 직접 계산해야 합니다.
  • 결제 체계: 문서는 API 콘솔 크레딧 차감만 설명합니다. 퍼플렉시티 앱의 Pro·Max 구독에 포함된다는 안내는 없습니다.
  • 단가 변동: Gemini 3.7·3.8 Flash 단가처럼 적용 기한(2026년 12월 31일)이 붙은 항목이 있으니 결제 전 최신 표를 다시 보세요.

정리

Orchestrator API는 여러 회사 모델을 한 키와 한 청구서로 쓰고, 같은 모델의 다른 제공처로 자동 재시도해 주는 개발자용 관문입니다. 요금은 모델별 토큰 단가 그대로이고 플랫폼 수수료는 없다고 회사는 밝혔습니다. 다만 상위 모델은 누적 구매액 등급에 묶여 있고, 자동 라우팅은 아직 프리뷰이며, 문서 일부에는 비공개 프리뷰 안내가 남아 있습니다.

이미 OpenRouter 같은 다른 게이트웨이나 각 회사 API를 직접 쓰고 있다면, 내가 주로 쓰는 모델의 단가와 필요한 등급, 자체 키 연결 필요 여부, 데이터 보관 조건부터 비교해 보는 것을 권합니다. 성공률·벤치마크 수치는 모두 퍼플렉시티 자체 측정이므로 실제 트래픽으로 소규모 시험을 먼저 해 보는 편이 좋습니다.

출처(자료 확인일: 2026년 11월 20일)

AI로 생성한 설명용 일러스트이며 실제 사건의 사진이 아닙니다.