BizRouter 비즈라우터

사용량 귀속과 비용 읽기

한 API 키를 여러 고객사나 서비스가 함께 쓸 때, 요청마다 누구의 사용량인지 헤더로 표시하면 사용량과 비용을 그 단위로 나눠 조회할 수 있습니다. 응답에 담기는 원화 비용을 읽는 방법도 함께 설명합니다.

사용량 귀속 헤더

사용량 귀속을 허용한 API 키에서만 기록합니다 string 값은 128자 이하이고 영문, 숫자, 점(.), 밑줄(_), 콜론(:), 하이픈(-)만 씁니다. 앞뒤 공백은 지우고, 빈 값은 보내지 않은 것으로 봅니다. 세 헤더 모두 모든 API에서 읽고, 모델 제공사로 전달하지 않습니다. 사용량 귀속을 허용하지 않은 키로 보내면 형식을 검사하지 않고 오류 없이 무시합니다. 기존 코드에 헤더를 먼저 넣어 두어도 안전합니다. 허용한 키에는 Usage-Subject와 Usage-Group을 반드시 보내도록 따로 설정할 수 있습니다. 설정된 헤더가 빠지면 요청을 거절합니다. API 키에서 켜는 방법 콘솔 서비스 API 키 에서 키의 수정 창을 열고 「사용량 귀속」 탭의 스위치를 켭니다. 새 키를 만들 때도 같은 탭에서 정합니다. 저장하면 다음 요청부터 바로 적용되며, 키를 수정할 수 있는 사람(관리자, 또는 구성원 본인의 키)이 바꿀 수 있습니다. 같은 탭에서 Usage-Subject와 Usage-Group을 필수로 받을지도 정합니다. 필수로 켜기 전에 호출 코드가 헤더를 보내는지 먼저 확인하십시오. 켜는 즉시 헤더가 없는 요청이 거절됩니다. 설정 상태는 GET /usage/v1/api-keys 응답의 usage_attribution_enabled , require_usage_subject , require_usage_group 값으로도 확인할 수 있습니다. 연동 전용 키는 설정이 고정되어 있어 콘솔에서 바꿀 수 없습니다. 웍스AI 합산 청구 조직에서는 키 주인에게 청구됩니다 웍스AI로 개설해 웍스AI 합산 청구를 쓰는 조직에서는 사용 금액이 요청을 보낸 API 키의 주인 계정에 올라가고, 그 구성원의 웍스AI 사용 한도가 적용됩니다. 사용량 귀속 헤더는 비용을 나눠 조회하는 용도이며, 금액이 올라가는 계정을 바꾸지 않습니다. 키 하나로 여러 직원을 대신해 호출하면 전체 금액이 그 키 주인 한 명의 웍스AI 계정과 한도에 올라갑니다. 직원별로 웍스AI 계정과 한도에 올리려면 직원이 각자 웍스AI로 로그인해 발급한 키를 쓰거나, 공용 키에서 아래 「직원 지정 청구」를 켜고 호출마다 직원을 지정하십시오. 웍스AI 사용 한도를 모두 쓴 구성원의 키는 한도가 초기화되거나 웍스AI 관리자가 한도를 조정할 때까지 사용할 수 없습니다. cURL Python Node.js

오류

사용량 귀속을 허용한 키에서만 납니다

직원 지정 청구

웍스AI 합산 청구 조직에서 공용 키로 호출하면서 직원별로 청구합니다 웍스AI 합산 청구 조직은 요청을 보낸 API 키의 주인 계정에 금액을 올립니다. 사내 에이전트나 포털이 키 하나로 여러 직원을 대신해 호출하면 전체 금액이 키 주인 한 명의 계정과 한도로 몰립니다. 키에서 직원 지정 청구를 켜면, 호출마다 X-BizRouter-Actor-Email 헤더에 직원 이메일을 넣어 그 직원의 웍스AI 계정과 한도에 올릴 수 있습니다. 켜는 곳은 콘솔 서비스 API 키의 수정 창 「사용량 귀속」 탭입니다. 웍스AI 합산 청구를 쓰는 조직의 소유자만 켤 수 있고, 조직 소유자가 발급한 키에서만 켤 수 있습니다. 연동 전용 키와 BizRouter가 직접 청구하는 계약 조직에서는 쓸 수 없습니다. 헤더가 없으면 지금처럼 키 주인에게 청구됩니다. 헤더가 있으면 지정한 직원의 요청으로 기록되어 요청 로그와 웍스AI 청구가 그 직원을 따릅니다. 어느 키로 호출했는지는 요청 로그의 키 항목에 그대로 남습니다. 지정한 직원은 이 조직의 구성원이어야 하고, 웍스AI 토큰의 기업이 공용 키 주인과 같아야 합니다(같은 숫자라도 일반 웍스AI와 공공/교육 웍스AI는 다른 회사로 봅니다). 웍스AI로 BizRouter에 로그인한 적이 있어야 하며, 웍스AI 한도가 남아 있어야 합니다. 하나라도 어긋나면 키 주인에게 청구하지 않고 요청을 거절합니다. 다른 웍스AI 기업의 직원은 없는 이메일과 똑같이 거절하므로, 키로는 그 직원이 있는지 알 수 없습니다. 이메일의 대소문자는 구분하지 않습니다. 청구는 웍스AI의 동의 항목이 아니라서, BizRouter가 웍스AI 로그인 화면에서 「회사의 API 키로 호출하면서 나를 지정하면 내 웍스AI 사용 한도가 쓰일 수 있다」는 안내를 보여 줍니다. 직원 지정은 이 안내가 나간 화면에서 로그인한 직원에게만 됩니다. 안내가 나가기 전에 로그인했던 직원은 BizRouter에 웍스AI로 한 번 다시 로그인해야 합니다. 직원의 웍스AI 토큰은 암호화해서 보관하고 청구와 한도 확인에만 씁니다. 토큰 갱신은 직원 한 명당 한 번에 하나씩만 하므로, 같은 직원을 지정한 요청이 한꺼번에 몰려도 직원의 웍스AI 로그인이 끊기지 않습니다. 웍스AI 한도는 청구 전달과 주기 점검에서 반영되므로, 한도를 넘긴 직후 몇 분 동안은 요청이 처리될 수 있습니다. 한도를 모두 쓴 직원의 본인 키가 멈추는 시점과 같습니다. 콘솔에서 정한 구성원별 월 한도는 그 구성원이 소유한 키의 사용량을 합산합니다. 공용 키로 지정해 쓴 사용량은 지정한 직원의 월 한도 계산에 들어가지 않으므로, 직원별 상한은 웍스AI 한도로 관리하십시오. 공용 키 주인의 월 한도는 지정한 직원과 관계없이 이 키의 요청에 그대로 적용됩니다. 일괄 처리와 파일, 대화 이어가기처럼 요청 사이에 이어지는 작업은 요청한 직원 기준으로 보입니다. 같은 작업의 요청은 같은 직원 헤더로 보내십시오. 일괄 처리용 파일을 헤더 없이 올리고 직원을 지정해 일괄 처리를 만들면 그 직원은 파일을 찾지 못할 수 있습니다. 공용 키의 주인 계정이 웍스AI 한도를 모두 쓰면 키 자체가 멈춥니다. 공용 키는 한도에 여유가 있는 소유자 계정으로 발급하십시오. 콘솔 사용 통계는 구성원이 소유한 키 기준으로 집계하므로, 지정된 직원 본인의 통계에는 공용 키 사용분이 나오지 않고 키 주인과 조직 소유자의 통계에 나옵니다. 직원별로 나눠 보려면 같은 요청에 X-BizRouter-Usage-Subject 로 사번을 함께 보내고 아래 사용량 조회 API로 묶어 보십시오. 웍스AI 청구는 지정한 직원을 따릅니다.

나눠서 조회하기

사용량 조회 API에서 헤더 값별로 묶고 거릅니다 GET /usage/v1/usage : 일별 사용량을 group_by=usage_subject 또는 group_by=usage_group 로 묶고, 같은 이름의 쿼리로 한 값만 거릅니다. 요청 수, 토큰, 원화 비용( cost_krw )을 돌려줍니다. 헤더 없이 보낸 요청은 값이 null 인 묶음으로 나옵니다. GET /usage/v1/logs : 요청 한 건씩 조회하며 usage_subject , usage_group , client_request_id 로 정확히 일치하는 요청을 거릅니다. 사용량 조회 API는 서비스 API 키가 아닌 별도의 사용량 조회 키로 호출합니다. 키 발급과 전체 필드는 사용량 조회 API 에 있습니다.

응답에서 비용 읽기

요청마다 원화 비용을 응답에 담아 돌려줍니다 API 필드 위치 값은 원(KRW)이며, 할인 등 조직의 계약 조건을 반영해 청구되는 금액입니다. 같은 요청이 사용량 조회 API와 콘솔 통계에 남는 금액과 같습니다. 다만 응답은 소수 계산 값을 그대로 담고, 조회 결과는 소수 여섯째 자리까지 저장한 값이라 끝자리가 다를 수 있습니다. 달러 가격에 적용하는 환율은 GET /v1/models 응답의 exchange_rate 와 같습니다. 모델별 원화 단가도 같은 응답에 있습니다. Chat Completions 스트리밍은 stream_options.include_usage 를 보내지 않아도 마지막 조각에 사용량과 비용을 담습니다. 모델 제공사가 사용량을 알려 주지 않은 요청은 이 조각을 보내지 않으며, 비용은 나중에 사용량 조회 API에서 확인합니다. 조직이 등록한 프로바이더 키(BYOK)로 처리한 요청은 프로바이더 요금을 BizRouter가 청구하지 않습니다. 계약에 BYOK 이용료가 있으면 그 금액만 비용에 들어갑니다. 스마트 라우팅 요청의 비용에는 요청 분석 비용이 함께 들어 있습니다. 프롬프트 캐시로 읽은 입력 토큰 수는 prompt_tokens_details.cached_tokens 에 있습니다.

X-BizRouter-Usage-Subject 사용량을 쓴 주체입니다. 고객사 ID, 사용자 ID처럼 비용을 나눠 볼 단위를 넣습니다. X-BizRouter-Usage-Group 주체를 묶는 단위입니다. 서비스, 부서, 프로젝트처럼 상위 묶음을 넣습니다. X-BizRouter-Client-Request-Id 클라이언트가 붙이는 요청 ID입니다. 자체 로그와 BizRouter 요청 로그를 한 건씩 맞춰 볼 때 씁니다. 400 bad_request 값이 128자를 넘거나 허용하지 않는 문자가 들어 있습니다. 400 bad_request 필수로 설정된 Usage-Subject 또는 Usage-Group 헤더가 없습니다(… is required for this API key.). 403 forbidden 콘솔에 로그인한 세션으로 이 헤더를 보냈습니다. 사용량 귀속은 API 키에서만 씁니다. 400 bad_request X-BizRouter-Actor-Email 값이 비어 있거나 이메일 형식이 아닙니다. 값이 이상하면 키 주인에게 청구하지 않고 거절합니다. 403 forbidden 이 키에서 직원 지정 청구를 켜지 않았습니다. 연동 전용 키이거나 조직 소유자가 발급한 키가 아닐 때도 같습니다. 403 forbidden 지정한 이메일이 이 조직의 구성원이 아닙니다. 다른 조직이나 다른 웍스AI 기업의 직원도 같은 응답입니다. 403 forbidden 지정한 직원이 웍스AI로 BizRouter에 로그인한 적이 없습니다. 403 forbidden 지정한 직원이 청구 안내가 나간 로그인 화면에서 로그인한 적이 없습니다. 그 직원이 웍스AI로 BizRouter에 다시 로그인해야 합니다. 403 forbidden 공용 키 주인이 웍스AI로 로그인한 계정이 아닙니다. 403 forbidden 지정한 직원이 웍스AI 사용 한도를 모두 썼습니다. 한도가 초기화되거나 웍스AI 관리자가 조정하면 다시 지정할 수 있습니다. 403 forbidden 지정한 직원의 웍스AI 로그인이 만료되었습니다. 그 직원이 웍스AI로 BizRouter에 다시 로그인해야 합니다. 403 forbidden 콘솔에 로그인한 세션으로 이 헤더를 보냈습니다. 직원 지정은 API 키에서만 씁니다. Chat Completions usage.cost 비스트리밍 응답, 그리고 스트리밍의 마지막 사용량 조각([DONE] 바로 앞) Responses response.usage.cost_krw 스트리밍의 response.completed 또는 response.incomplete 이벤트. 비스트리밍 응답에는 없습니다. Messages usage.cost_krw 비스트리밍 응답, 그리고 스트리밍의 message_delta 이벤트 이미지 API · 임베딩 · 리랭킹 · Search usage.cost 응답 본문 동영상 cost_krw 생성 요청과 상태 조회 응답. 원 단위 정수입니다. 음성 합성 · 음성 인식 없음 사용량 조회 API나 콘솔에서 확인합니다.

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