배치 API
바로 답이 필요 없는 요청을 묶어 보내고 24시간 안에 결과를 받는 비동기 API입니다. OpenAI Batch와 Anthropic Message Batches의 경로·요청 본문·응답 객체를 그대로 따르므로 각 공식 SDK를 주소만 바꿔 사용할 수 있습니다. 배치 요청은 표준 단가의 60%로 청구됩니다.
가격
제공사 배치 단가(표준가의 50%)에 20%를 더한 금액입니다 OpenAI와 Anthropic은 배치 요청의 모든 토큰 항목(입력·출력·캐시 읽기·캐시 쓰기)을 표준가의 50%로 청구합니다. BizRouter 배치 단가는 그 금액에 20%를 더한 표준 단가 × 0.6 이며, 입력 길이에 따른 단계 단가도 같은 비율로 적용됩니다. 예: anthropic/claude-sonnet-5.5 (USD / 100만 토큰) 항목 표준 요청 배치 요청 실패(errored)·취소(canceled)·만료(expired)된 요청은 청구하지 않습니다. 제공사도 청구하지 않습니다. 조직 마크업, 할인 이벤트, BYOK 수수료 등 계약 조건은 일반 요청과 같이 적용됩니다. 배치를 만들 때 모든 요청의 입력과 출력 상한( max_tokens )으로 계산한 최대 비용을 크레딧에서 잡아 두고, 배치가 끝나면 실제 사용량만 차감한 뒤 나머지를 돌려줍니다. 최대 비용이 잔액이나 API 키 한도를 넘으면 402 로 거절합니다. 출력 상한이 없는 요청은 모델의 최대 출력으로 계산하므로 출력 상한을 실제 필요한 만큼으로 지정하면 더 큰 배치를 보낼 수 있습니다. 배치가 끝나 정산될 때까지 보류액은 후불 월 한도, API 키 한도, 구성원 월 한도에 사용량처럼 포함됩니다. 그동안에는 다음 배치뿐 아니라 일반 요청도 그만큼 일찍 한도에 닿습니다. 보류액은 출력 상한으로 계산한 최대 비용이라 실제 청구액보다 큽니다. 배치 하나는 사용 기록 한 건으로 남습니다. 토큰은 성공한 요청의 합계입니다. client_request_id 에는 배치를 만들 때 보낸 X-BizRouter-Client-Request-Id 값이, 보내지 않았으면 배치 id가 기록됩니다.
엔드포인트
두 형식 중 쓰시는 SDK에 맞는 쪽을 사용합니다
엔드포인트 · Anthropic 호환 (Message Batches)
Claude Code용 주소( /claude/v1/messages/batches )도 같습니다. 인증은 Authorization: Bearer <API Key> 또는 x-api-key 헤더를 사용합니다.
지원 모델
OpenAI와 Anthropic이 직접 제공하는 텍스트 채팅 모델입니다 OpenAI 호환 형식: Chat Completions로 호출하는 openai/* 텍스트 모델은 OpenAI Batch에서, anthropic/* 모델은 Anthropic Message Batches에서 실행됩니다. Anthropic 모델도 입력 파일과 결과 파일은 Chat Completions 형식 그대로입니다. Anthropic 호환 형식: Anthropic 모델만 지원합니다. Responses API로만 호출하는 모델( openai/gpt-6-astra , openai/gpt-6.1-terra , openai/gpt-6.2-astra , openai/gpt-6.2-sol , 이름이 -pro · -codex 로 끝나는 모델 등)과 이미지·음성 모델은 배치로 보낼 수 없으며 400 을 반환합니다. 이 모델들은 일반 요청으로 호출하십시오. GPT-5.4 이상 모델의 배치 요청에 도구( tools )가 있으면 추론 없이( reasoning_effort: "none" ) 실행됩니다. 도구와 함께 none 이 아닌 추론 강도를 지정한 줄은 오류로 거절합니다. 도구와 추론이 함께 필요하면 일반 요청을 사용하십시오. 그 밖의 제공사 모델(Gemini 등)과 Smart Routing 모델( bizrouter/route )은 배치로 보낼 수 없으며 400 을 반환합니다.
사용 예
OpenAI 형식으로 Claude Sonnet 5.5 배치 실행 Python (OpenAI SDK) Python (Anthropic SDK) cURL
프롬프트 캐싱
cache_control을 배치 요청에서도 사용할 수 있습니다 Anthropic 모델은 cache_control (5분·1시간)을 그대로 받으며, 캐시 읽기·쓰기에도 배치 단가(표준 × 0.6)가 적용됩니다. 배치는 요청이 동시에 처리되므로 캐시 적중은 보장되지 않습니다. 같은 긴 시스템 프롬프트를 여러 요청이 공유한다면 1시간 캐시를 사용하는 편이 적중률이 높습니다.
제한과 동작
공식 API와 다른 점도 함께 정리합니다 배치 하나에는 모델 하나만 사용할 수 있습니다 (Anthropic 형식도 같습니다). 입력 파일과 Message Batches 요청 본문은 각각 100MB까지이며, 요청 수는 OpenAI 형식 5만 건, Anthropic 형식 10만 건까지입니다. OpenAI 형식의 endpoint 는 /v1/chat/completions 만, completion_window 는 24h 만 받습니다. stream: true , 호출 건수로 과금되는 서버 도구(웹 검색 등), BizRouter 전용 옵션( models 폴백 목록, 검색 플러그인 등)은 배치에서 사용할 수 없습니다. OpenAI 형식에서 요청 줄에 오류가 있으면 OpenAI와 같이 status: "failed" 배치와 errors.data[].line 로 알려 드리며, 이 경우 청구나 크레딧 보류가 없습니다. Anthropic 형식은 400 으로 알려 드립니다. Anthropic 모델을 OpenAI 형식으로 보낼 때 custom_id 는 ^[a-zA-Z0-9_-]{1,64}$ 형식이어야 합니다. BizRouter가 우회 라우팅 정책을 적용하고 있는 모델, Corepin 콘텐츠 보호를 쓰는 조직, 요청마다 위해성 검사를 하는 모델은 아직 배치를 지원하지 않습니다. 「무보관 제공사만 사용」 정책을 켠 조직은 배치를 사용할 수 없습니다. OpenAI와 Anthropic은 배치 입력과 결과를 약 30일 보관하며, 무보관 계약이 배치에는 적용되지 않습니다. 조직마다 동시에 진행 중인 배치는 50개까지입니다. 금칙어와 개인정보 마스킹은 배치의 모든 요청에 일반 요청과 같이 적용됩니다. 금칙어가 들어 있는 요청이 있으면 배치 전체를 거절합니다. BizRouter Guard는 배치 요청을 검사하지 않습니다. 요청 줄의 guard 를 켜거나 X-BizRouter-Guard 헤더를 켜서 보내면 400 으로 거절합니다. 배치와 입력 파일은 만든 구성원(그 구성원의 모든 API 키)과 조직 소유자(owner)만 조회·취소·삭제할 수 있습니다. 다른 구성원에게는 없는 id와 같이 404 입니다.
취소와 실패
취소한 뒤 청구되는 것과 보류가 풀리는 때 진행 중인 배치는 두 형식 모두 취소할 수 있습니다. 취소 전에 이미 처리된 요청은 결과를 받을 수 있고 청구됩니다. 나머지 요청은 청구하지 않습니다. 크레딧 보류는 취소 요청 즉시가 아니라 제공사가 취소를 마치고(OpenAI는 최대 10분) BizRouter가 정산한 뒤에 풀립니다. 그 전에는 새 배치나 요청이 한도에 걸릴 수 있습니다. 24시간 안에 끝나지 못해 만료된 배치도 처리된 요청만 청구합니다. 배치를 만들 때 제공사가 응답하지 않으면 502 와 함께 배치 id를 알려 드립니다. 이 배치는 BizRouter가 제공사에서 확인해 15분쯤 안에 진행 중 또는 실패로 정리하며, 만들어지지 않았으면 보류를 풉니다. 같은 배치가 두 번 만들어지지 않도록 그 전에는 다시 제출하지 마십시오. 이 응답에는 SDK가 자동으로 재시도하지 않도록 x-should-retry: false 가 붙습니다.
데이터 보관
결과는 BizRouter에 저장하지 않습니다 입력 파일은 기본 30일 보관 후 삭제됩니다. 올릴 때 expires_after[anchor]=created_at , expires_after[seconds] (3,600~2,592,000초)로 줄이거나, 언제든 DELETE /v1/files/ {file_id} 로 지울 수 있습니다. 지운 파일과 만료된 파일은 그 즉시 읽을 수 없고 10분 안에 저장소에서 삭제되며, 저장소의 복구용 이전 버전은 30일 뒤 자동으로 지워집니다. 입력 파일은 올린 내용 그대로 보관됩니다. 개인정보 마스킹은 제공사로 보내는 요청에 적용되며, 보관된 파일 자체는 바꾸지 않습니다. 감사 로그 저장을 끈 조직도 입력 파일은 위 기간 동안 보관됩니다. OpenAI 모델 배치에서 BizRouter가 OpenAI에 올리는 변환 입력 파일은 배치 정산이 끝나면 OpenAI에서 삭제합니다. 결과는 BizRouter가 저장하지 않고 조회할 때마다 제공사에서 가져와 돌려드립니다. 제공사 보관 기간(OpenAI 30일, Anthropic 29일)이 지나면 조회할 수 없습니다. OpenAI 모델 배치는 output_expires_after 로 결과 보관 기간을 줄일 수 있습니다. Anthropic 모델 배치는 이 값을 받지 않습니다( 400 ). 감사 로그에는 요청·응답 본문 없이 배치 요약 한 줄만 남습니다. 결과 삭제 정산까지 끝난 배치의 결과는 보관 기간 전에 지울 수 있습니다. OpenAI 형식은 결과 파일이나 오류 파일을 DELETE /v1/files/ {file_id} 로 삭제합니다. Anthropic 모델로 실행한 배치는 두 파일이 하나의 결과에서 나오므로 어느 한쪽을 지우면 둘 다 지워집니다. Anthropic 형식은 배치를 DELETE 로 삭제합니다. 정산 중이거나 검토 중인 배치는 409 입니다.
POST /v1/files 배치 입력 파일 올리기 (purpose=batch) GET /v1/files 올린 입력 파일 목록 GET /v1/files/{file_id} 파일 정보 GET /v1/files/{file_id}/content 입력 파일, 결과 파일(output_file_id), 오류 파일(error_file_id) 내용 DELETE /v1/files/{file_id} 입력 파일 삭제, 정산이 끝난 배치의 결과·오류 파일 삭제 POST /v1/batches 배치 만들기 GET /v1/batches 배치 목록 (after, limit) GET /v1/batches/{batch_id} 배치 상태 POST /v1/batches/{batch_id}/cancel 배치 취소 POST /v1/messages/batches 배치 만들기 (requests[].custom_id, params) GET /v1/messages/batches 배치 목록 (before_id, after_id, limit) GET /v1/messages/batches/{batch_id} 배치 상태 GET /v1/messages/batches/{batch_id}/results 결과 (JSONL) POST /v1/messages/batches/{batch_id}/cancel 배치 취소 DELETE /v1/messages/batches/{batch_id} 끝난 배치 삭제 입력 $2.00 $1.20 출력 $10.00 $6.00 캐시 읽기 $0.10 $0.06 캐시 쓰기 (5분) $2.50 $1.50 캐시 쓰기 (1시간) $4.00 $2.40