API 연동과 운영
OpenAI SDK 호환 범위, 모델 선택, 사용량 구분과 오류 처리처럼 API를 연동하고 운영할 때 자주 확인하는 내용입니다.
자주 묻는 질문
기존 OpenAI SDK를 사용할 수 있나요?
지원되는 Chat Completions와 Responses 기능에서는 사용할 수 있습니다. API 키와 base_url 을 BizRouter 값으로 바꾸면 됩니다. OpenAI의 모든 endpoint와 parameter를 지원한다는 의미는 아니므로 각 API 문서의 지원 범위를 확인해야 합니다.
어떤 model ID를 사용해야 하나요?
GET /v1/models 가 현재 API 키로 사용할 수 있는 모델 목록입니다. 문서의 예제 model ID를 운영 설정의 source of truth로 사용하지 마세요. 자세한 응답 필드는 모델 문서 에서 확인할 수 있습니다.
API 요청은 어디에서 보내야 하나요?
브라우저가 아닌 고객의 backend, serverless function 또는 안전한 server 환경에서 보내세요. 서비스 API 키를 frontend bundle, mobile app 또는 공개 저장소에 포함하면 안 됩니다.
사용량을 고객이나 서비스별로 구분할 수 있나요?
콘솔의 서비스 API 키 수정 창에서 「사용량 귀속」을 켠 뒤 X-BizRouter-Usage-Subject , X-BizRouter-Usage-Group , X-BizRouter-Client-Request-Id 를 전송할 수 있습니다. 자세한 방법은 사용량 귀속 헤더 에 있습니다.
CLI나 코딩 에이전트로 콘솔을 관리하면 API 키 권한이 늘어나나요?
아닙니다. API 키는 예전과 같이 모델 호출에만 쓰입니다. bizrouter CLI의 콘솔 관리 명령과 MCP 도구는 브라우저에서 승인한 사람의 콘솔 세션으로 동작하고, 할 수 있는 일은 그 사람이 웹 콘솔에서 할 수 있는 것과 같습니다. 「사용량 조회 API」 키도 별개입니다. 자세한 내용은 CLI 문서 의 「자주 묻는 것」에 있습니다.
사용량 데이터를 API로 조회할 수 있나요?
관리자(owner)가 설정 > API 연동 > 사용량 조회 API에서 별도의 사용량 조회 API 키를 발급해야 합니다. 서비스 API 키와 용도가 다릅니다. 자세한 내용은 사용량 조회 API 문서 에 있습니다.
403이면 모두 재시도하면 안 되나요?
대부분의 403은 설정이나 잔액을 먼저 수정해야 합니다. 다만 prepaid_credit_temporarily_reserved 는 진행 중 요청의 임시 예약으로 발생하며 details.retryable=true 일 때 짧은 backoff 후 재시도할 수 있습니다.
모델 제공사의 오류도 같은 JSON 구조로 반환되나요?
아닐 수 있습니다. BizRouter 자체 오류는 표준 구조를 사용하지만 모델 제공사의 오류는 원본 HTTP status와 body가 전달될 수 있습니다. 안전한 parser와 재시도 예제는 오류 처리 문서 에 있습니다.
스마트 라우팅은 모든 endpoint에서 동작하나요?
아닙니다. Chat Completions, Responses, Messages API에서 동작합니다. Responses에서는 OpenAI 모델만 후보로 선택되고, Responses와 Messages에서는 실패한 모델을 다른 모델로 다시 시도하지 않습니다. 설정 절차는 스마트 라우팅 가이드 에 있습니다.
Search는 웹 검색 API인가요?
아닙니다. Search는 모델이 질문을 이해하고 법령·기업 공시·부동산 실거래·국가통계·교통·논문·웹 검색 등 50종이 넘는 내장 데이터 출처 중 필요한 것을 골라 실제 값을 조회하고, 여러 출처를 교차 확인한 뒤 출처와 함께 답하는 기능입니다. POST /v1/search 로 호출하거나, 기존 Chat Completions 코드에서 모델 이름 뒤에 :search 를 붙이면 됩니다. 자세한 내용은 Search 문서 에 있습니다.
분당 호출 수 제한이 있나요?
있습니다. API 키마다 endpoint별로 분당 요청 수를 제한하며, 기본값은 분당 60회입니다. 한도를 넘으면 429 응답과 Retry-After 헤더가 돌아옵니다. 대량 작업이나 동시 사용자 때문에 더 필요하면 로 예상 사용량을 알려 주시면 한도 조정을 검토합니다. 자세한 내용은 요청 한도 문서 에 있습니다.
우리 서비스의 이용자에게 결과를 제공하는 용도로 써도 되나요?
네. 서비스의 backend에서 API를 호출해 그 결과를 서비스 이용자에게 제공할 수 있고, 개발용과 운영용 사이에 요금이나 조건의 차이는 없습니다. 이용자별 사용량을 나누어 보려면 사용량 귀속 헤더 를 사용합니다.
Batch API나 파인튜닝을 지원하나요?
Batch API는 지원합니다. OpenAI 형식( /v1/files , /v1/batches )과 Anthropic 형식( /v1/messages/batches )으로 OpenAI·Anthropic 모델을 묶어 보내면 24시간 안에 결과를 받으며, 표준 단가의 60%로 청구됩니다. 자세한 내용은 배치 API 문서 에 있습니다. 파인튜닝 API는 없고, 모델 제공사에서 따로 파인튜닝한 모델을 BizRouter로 호출할 수도 없습니다. 호출할 수 있는 모델은 GET /v1/models 목록에 있는 모델입니다.
쓰고 싶은 모델이 목록에 없으면 어떻게 하나요?
로 모델 이름과 용도, 예상 사용량을 보내 주시면 추가를 검토합니다.
model_blacklisted와 api_key_model_not_allowed는 어떻게 다른가요?
model_blacklisted 는 조직의 「모델 접근 정책」에서 막아 둔 모델이라는 뜻입니다. 이 정책은 관리자(owner)만 바꿀 수 있습니다. api_key_model_not_allowed 는 요청에 쓴 API 키에 허용 모델이 정해져 있고, 요청한 모델이 그 목록에 없다는 뜻입니다. 「서비스 API 키」에서 그 키의 허용 모델을 고치거나 다른 키를 사용합니다.
지정한 모델로만 요청이 가나요? 특정 모델만 쓰게 막을 수 있나요?
모델 이름을 직접 지정한 요청은 그 모델로 보냅니다. 그 모델이 실패했을 때에만 요청에 적은 폴백 모델이나 조직의 폴백 정책 에 있는 대체 모델로 넘어갈 수 있습니다. 스마트 라우팅은 모델을 bizrouter/route 로 보낸 요청에만 동작합니다. 모델마다 어느 제공사를 거치는지는 모델 목록 에서 확인할 수 있습니다. 조직 전체에서 특정 모델이나 제공사를 막으려면 관리자(owner)가 「모델 접근 정책」에서 차단하고, 키마다 쓸 수 있는 모델을 정하려면 API 키의 허용 모델을 지정합니다.