BizRouter 비즈라우터

Chat Completions API

OpenAI 호환 Chat Completions 엔드포인트를 통해 다양한 LLM 프로바이더의 모델을 통합적으로 호출할 수 있습니다. BizRouter가 지원하는 Chat Completions 기능에서는 OpenAI SDK를 사용할 수 있으며, 모델별 확장 parameter와 multi-provider 호출을 제공합니다.

엔드포인트 개요

Chat Completions API 요청 엔드포인트 POST /v1/chat/completions 대화 메시지 배열을 기반으로 AI 응답을 생성합니다. 스트리밍 및 비스트리밍 모두 지원됩니다.

엔드포인트 개요 · 인증

Authorization: Bearer sk-br-v1-YOUR_API_KEY 또는 X-API-Key: sk-br-v1-YOUR_API_KEY 헤더를 사용합니다.

요청 형식

ChatCompletionRequest 인터페이스 정의

스마트 라우팅

라우팅 설정에 따라 실제 모델과 Provider를 선택하는 기능 Chat Completions 요청에서 bizrouter/route 또는 설정 화면에 표시된 bizrouter/route/<slug> 를 사용하면 해당 Route 정책으로 실제 Model·Provider가 선택됩니다. 안전한 일시적 Provider 오류에서 다음 후보로 전환하는 fallback 재시도는 Chat Completions에서만 실행됩니다. 실제 데이터를 찾아 답해야 하는 요청에는 bizrouter/search 또는 모델 이름 뒤에 :search 접미사를 붙이십시오. 법령·공시·실거래·통계·웹 검색 등 50종 넘는 출처를 모델이 직접 조회합니다. 전용 엔드포인트 POST /v1/search 도 제공됩니다. 설정 가이드 Search 문서

Anthropic Beta 헤더 전달

Anthropic 모델 호출 시 베타 기능 플래그 전달 /v1/chat/completions 에서도 Anthropic 베타 헤더를 직접 전달할 수 있습니다.

Anthropic Beta 헤더 전달 · 2) 요청 바디 extra 방식

우선순위 및 적용 범위 같은 요청에서 헤더와 바디를 함께 보내면 anthropic-beta 헤더 값이 우선합니다. 이 값은 Anthropic으로 라우팅되는 요청에만 적용됩니다. 검토된 기능 계열(interleaved-thinking, prompt-caching, prompt-caching-scope, extended-cache-ttl, output-128k, token-efficient-tools, fine-grained-tool-streaming, structured-outputs, effort, context-management, thinking-token-count, mid-conversation-system, advanced-tool-use, computer-use, pdfs, claude-code, oauth, web-search)만 전달되며, 그 밖의 토큰(context-1m 포함)은 제거됩니다. 제거된 토큰은 응답 헤더 x-bizrouter-beta-dropped 에 표시됩니다. code-execution, files-api, mcp-client, skills 계열은 400으로 거절됩니다.

응답 형식

ChatCompletionResponse 인터페이스 정의

응답 형식 · 응답 예시

BizRouter 추가 필드 usage.cost 는 BizRouter가 추가로 제공하는 필드로, 해당 요청의 KRW 비용을 나타냅니다. 추론 모델 사용 시 usage.thinking_tokens 도 포함됩니다. 프롬프트 캐싱이 적용된 요청에는 prompt_tokens_details.cached_tokens (OpenAI 표준)와 함께 BizRouter 확장 필드인 cache_read_input_tokens , cache_creation_input_tokens 가 포함됩니다. prompt_tokens 는 항상 캐시 read/write 토큰을 포함한 전체 입력 토큰 수입니다.

메시지 형식

messages 배열의 구조와 역할

메시지 형식 · 역할(Role) 설명

system AI의 행동과 성격을 정의하는 시스템 프롬프트. 대화의 맨 처음에 위치합니다. user 사용자의 입력 메시지 assistant AI의 이전 응답. 대화 컨텍스트 유지에 사용됩니다. tool 도구 호출 결과를 반환할 때 사용. tool_call_id 와 함께 사용됩니다.

메시지 형식 · 멀티모달 메시지 (이미지 포함)

Anthropic·Google 모델은 JPEG, PNG, GIF, WebP 이미지를 한 장당 5MB까지 받고, OpenAI·xAI 모델은 요청 본문 20MB 안에서 각 제공사 기준을 따릅니다. 자세한 한도는 제한 사항 에 있습니다.

샘플링 파라미터

토큰 선택 확률 및 다양성 제어 temperature number 1.0 낮을수록 결정적, 높을수록 창의적 범위: 0.0 ~ 2.0 top_p number 1.0 누적 확률 p 이내 토큰만 고려 (Nucleus Sampling) 범위: 0.0 ~ 1.0 top_k integer 비활성화 상위 K개 토큰만 고려 범위: 1 ~ N min_p number 0.0 최소 확률 임계값 (최대 확률 대비 비율) 범위: 0.0 ~ 1.0 seed integer 랜덤 결정론적 생성을 위한 시드 값 범위: - 샘플링 조합 팁 temperature와 top_p를 동시에 조정하면 예측하기 어려운 결과가 나올 수 있습니다. 한 번에 하나의 파라미터만 조정하는 것이 좋습니다.

페널티 파라미터

반복 방지 및 다양성 증가 frequency_penalty number 0.0 등장 횟수에 비례하여 페널티 부과 (양수: 반복 감소) 범위: -2.0 ~ 2.0 presence_penalty number 0.0 등장 여부에 따라 페널티 (양수: 새 주제 탐색 유도) 범위: -2.0 ~ 2.0 repetition_penalty number 1.0 HuggingFace 스타일 반복 페널티 (1.0 = 페널티 없음) 범위: 1.0 ~ 2.0

출력 제어

생성 길이 및 종료 조건 max_tokens integer 모델별 상이 생성할 최대 토큰 수 stop string | string[] 생성 중지 시퀀스 (최대 4개)

기능 가이드

Chat Completions에서 쓰는 기능별 사용법은 개발자 가이드의 기능 가이드에 따로 정리했습니다. 스트리밍 — 응답을 SSE(Server-Sent Events) 청크로 받는 방법과 청크 구조, 사용량 보고, 스트림 종료 처리입니다. 도구 호출 — 모델이 함수(도구)를 호출하도록 요청하고 결과를 이어 받는 방법입니다. 구조화된 출력 — 응답을 JSON이나 지정한 JSON Schema 형식으로 받는 방법입니다. 추론 (Reasoning) — 추론 모델이 답하기 전에 생각하는 양을 정하고, 추론 토큰이 어떻게 과금되는지 설명합니다. 프롬프트 캐싱 — 반복되는 프롬프트 앞부분을 캐시해 비용과 지연을 줄이는 방법입니다. Claude, GPT, Gemini 모델별로 방법이 다릅니다. 프로바이더별 파라미터 — GPT-5/GPT-6, Gemini, Perplexity 모델에만 있는 확장 파라미터와 프로바이더별 지원 범위입니다.

Responses API 자동 변환

Responses 전용 모델을 Chat Completions로 호출 Responses API 전용 모델(o3-pro, GPT-5 Codex 등)을 이 엔드포인트로 호출하면 BizRouter가 자동으로 Responses API 형식으로 변환하여 처리합니다. 기존 코드를 수정하지 않고 모델명만 변경하면 됩니다. 자세한 내용 Responses API의 상세 사양, 백그라운드 모드, 서버 측 대화 저장 등의 기능은 Responses API 문서 를 참조하십시오.

요청 예시

다양한 사용 사례별 파라미터 조합

주식회사 AI3 | 서울 강남구 영동대로85길 34 | support@bizrouter.ai