문서
키 그룹
고객마다 전용 API 키를 발급해 그룹으로 묶고, 어떤 기간이든 고객별·키별 지출을 확인하며, 각 고객이 한 달에 쓸 수 있는 금액에 상한을 둘 수 있습니다. 계정도 잔액도 하나입니다.
그룹은 계정 안의 API 키 폴더로, 예를 들어 고객마다 하나씩 만듭니다: CID000001, CID000002. 그룹 안의 키도 다른 키와 똑같이 API를 호출하며, 그룹에는 별도의 잔액, 충전, 로그인이 없습니다. 그룹에는 소속된 모든 키의 합계에 대한 월간 한도를 둘 수 있습니다. 키는 한 그룹에 속하거나 어느 그룹에도 속하지 않습니다.
세 단계로 그룹 설정하기
한 달 치를 확인하고 내보내기
사용량 페이지 상단에서 ‘지난달’(또는 ‘이번 달’, 날짜를 고르려면 ‘직접 지정’)을 선택합니다. ‘API 키별’에서 각 그룹 제목 줄에 그 그룹의 비용과 호출 수가 표시됩니다. 상단의 그룹 메뉴로 페이지 전체를 한 그룹(수치, 차트, 모델, 호출)으로 좁힐 수 있습니다. ‘CSV 내보내기’는 페이지에 보이는 내용, 즉 같은 기간과 같은 그룹을 키별 또는 일별로 내려받습니다.
키별 파일은 키와 그룹마다 한 줄이며, 파일 이름은 kunavo-cost-by-key_2026-10-01_2026-10-31.csv 형식입니다. 기간 안에 호출이 있었던 모든 키(폐기된 키 포함)를 각 호출이 이루어진 그룹 아래에 싣고, 현재 그룹에서 호출이 없었던 활성 키도 0으로 싣기 때문에 각 고객의 키 목록이 빠짐없이 나옵니다. 그룹은 대시보드와 같은 순서이고, 그룹 안의 키는 지출이 많은 순, 그룹 미지정 키는 맨 뒤입니다. 일별 파일은 맨 앞에 date 열이 있고, 키가 한 그룹에서 호출한 날마다 한 줄입니다.
| 열 | 내용 |
|---|---|
group | 호출이 이루어진 그룹입니다. 어느 그룹에도 속하지 않은 호출은 비어 있습니다. 이후 삭제된 그룹은 이름 뒤에 (deleted)이(가) 붙습니다. |
key_name | 키 이름. |
key_prefix | 대시보드에 표시되는 키의 앞부분. 키 전체는 절대 들어가지 않습니다. |
key_status | active 또는 revoked. |
calls | 기간 중 이 키로 한 호출 수. |
errors | 그중 실패한 호출 수. 실패한 호출은 비용이 들지 않습니다. |
input_tokens | 입력 토큰 수(캐시 읽기와 캐시 쓰기 포함). |
output_ | 출력 토큰 수. |
cached_ | 입력 토큰 중 프롬프트 캐시에서 읽은 토큰. |
cache_ | 입력 토큰 중 프롬프트 캐시에 쓴 토큰. |
cost_usd | 호출에 청구된 금액(미국 달러, 소수점 이하 여덟 자리). |
=, +, -, @ 중 하나로 시작하는 그룹 이름이나 키 이름은 앞에 아포스트로피를 붙여 기록하므로, 스프레드시트에서 수식으로 실행되지 않고 텍스트로 표시됩니다.그룹마다 한 달 지출에 상한 두기
API 키 페이지에서 그룹 메뉴를 열고 ‘월간 한도 설정’을 선택합니다. 한도는 그룹의 모든 키가 달력 기준 한 달(UTC) 동안 함께 쓴 금액, 즉 각 키가 그 그룹에 속해 있던 동안의 호출로 계산합니다. 그룹을 한도 넘게 만드는 요청은 402로 거부되며 요금이 청구되지 않습니다. 비워 두면 한도가 없고, 0으로 설정하면 키를 폐기하지 않고 그룹의 모든 키를 일시 중지합니다.
각 키 자체의 월간 한도도 그대로 적용되며, 먼저 도달한 한도가 요청을 거부합니다. 그룹 제목 줄에는 이번 달 지출과 한도가 표시되고, 요청이 거부되기 시작하면 ‘한도 도달’, 한도가 0이면 ‘일시 중지됨’이 표시됩니다.
그룹이나 자체 한도가 있는 키가 이번 달 월간 한도의 80%를 쓰면 Kunavo가 계정 이메일로 알려 드리고, 그 한도로 요청이 거부되기 시작하면 한 번 더 알려 드립니다. 한도마다 각 이메일은 한 달에 한 번까지입니다.
수치 계산 방식
- 비용은 청구된 금액입니다. 각 호출의 비용은 호출이 끝났을 때 잔액에서 차감된 금액입니다. 실패한 호출은 비용이 들지 않습니다.
- 월과 일은 UTC 기준입니다. 이번 달은 1일 00:00 UTC에 시작합니다. 예를 들어 양곤(UTC+6:30)에서는 10월이 현지 시간 11월 1일 06:30에 끝납니다. 사용량 페이지에는 표시 중인 기간의 날짜가 나옵니다.
- 호출은 그 시점에 키가 속해 있던 그룹에 집계됩니다. 키를 다른 그룹으로 옮기면 그 뒤의 호출만 새 그룹에 집계되고, 이전 호출은 원래 그룹에 남습니다. 그래서 API 키 페이지에서 그룹의 이번 달 합계가 지금 그 아래 표시된 키들의 합과 다를 수 있습니다.
- 폐기된 키는 원래 그룹에 남습니다. 폐기 전에 쓴 금액은 계속 그 그룹 합계에 포함되고 내보내기에도 나옵니다.
- 삭제한 그룹의 호출은 남습니다. 사용량 페이지와 내보내기에서 그 그룹 이름 아래에 삭제됨으로 표시된 채 남고, 같은 이름은 새 그룹에 다시 쓸 수 있습니다.
- 세 곳, 같은 수치. 같은 달력 월이라면 API 키 페이지의 그룹 합계, 사용량 페이지 ‘이번 달’의 그룹 합계, CSV에서 그 그룹 행들의 합은 센트 단위까지 같습니다.
자주 묻는 질문
- 그룹마다 잔액이 따로 있나요? 아니요. 모든 그룹이 계정의 잔액 하나를 함께 씁니다. 한 고객의 지출을 제한하려면 그 고객의 그룹이나 각 키에 월간 한도를 설정하세요.
- 고객이 로그인해서 사용량을 볼 수 있나요? 아니요. 그룹은 본인만 볼 수 있습니다. 각 키는 GET /v1/usage로 자신의 사용량을 조회할 수 있지만, 여기에는 그룹이 나오지 않습니다. 그룹에 월간 한도가 있으면
GET /v1/balance는 그 키에 한도와 그룹 전체의 이번 달 지출을 보여 주지만, 그룹 이름은 보여 주지 않습니다. - 그룹을 삭제하면 어떻게 되나요? 직접 고릅니다. 키를 계속 쓰면서 이후로는 그룹 미지정으로 둘 수도 있고, 그룹과 함께 폐기할 수도 있습니다. 어느 쪽이든 그 키들이 한 호출은 그룹 이름 아래에 남습니다.
- 키를 한 고객에게서 다른 고객에게로 옮기려면? 다른 고객의 그룹으로 옮기세요. 그 뒤의 호출은 그 그룹에 집계되고, 이전 호출은 첫 번째 고객에게 남습니다.
- 이 밖의 기간도 볼 수 있나요? 네. 사용량 페이지에서 ‘직접 지정’을 선택하고 최대 90일을 고르세요. 프로그램에서는 GET /v1/usage로 같은 기간 한 키의 일별 비용을 받을 수 있습니다.
고객의 키를 직접 다루지 않고 자체 도구에서 만들고, 그룹으로 묶고, 한도를 두고, 폐기하려면 관리 API를 사용하세요. 관리 API의 키는 별도의 자격 증명이며 그 API에서만 작동합니다.