크레딧
충전 · 차감, 잔액은 GET /v1/credits 의 balance_credits 로 봐요.
- 산 크레딧은 만료되지 않아요 — 개인·기업·학교·기관 구매 모두 같아요.
- 국고·사업비로 충전하신 경우, 잔액 만료와 별개로 그 사업의 인정 사용 기간 안에 찍힌 사용분만 해당 재원 정산에 들어가요. 인정 기간과 잔여분 처리는 계약서에 정해요. 재원(국고 사업비 · 교비 · 기타 지원금)은 그 지갑을 쓰기 전에 고객센터로 알려 주세요 — 사용 기록이 하나라도 생긴 지갑은 재원을 바꿀 수 없어서(시험 호출 한 번으로도 생길 수 있어요) 다른 재원이면 지갑을 새로 열어야 해요. 사업 이름 · 인정 기간은 계약서대로 저희가 지갑에 적어 드려요(쓰기 시작한 뒤에도 돼요 — 고객센터에 말씀해 주세요). 재원이나 기간이 적힌 지갑엔 대시보드 AI API 화면에 재원 카드(「서비스 지원기간」 · 「사업비 인정 사용기간」 · 「잔여분 처리」)가 떠요. 사업이 끝난 뒤 남은 크레딧은 그 카드의 「잔여분 처리」대로예요(비었으면 계약서대로).
- 다 쓰면 스쿨오더 · 오피스오더의 「원포트 AI API 크레딧」 상품에서 다시 사요(어디서 사나는 https://oneport.kr/buy). 이 상품은 1만 · 5만 · 10만 · 25만 · 50만 크레딧 묶음으로 팔아요(1 크레딧 부가세 포함 2원). 주문서의 「키 받을 이메일」에 쓰시던 지갑 메일을 적으면 같은 지갑에 채워지고 키는 그대로 써요 — 같은 지갑에 채우시려면 이 칸을 꼭 적어 주세요. 비우면 로그인했든 안 했든 주문서의 증빙 받을 이메일의 지갑으로 가요 — 행정실 메일이면 행정실 메일의 지갑이고, 그 메일의 지갑이 없으면 새로 생겨요(로그인한 계정 메일과 달라도 그래요). 다만 대시보드 안에서 낸 주문(학교의 「우리 학교 구매안」에서 이어진 주문도)은 이 칸이 없고 그 주문을 낸 분(로그인한 계정)의 지갑으로 가요 — 다른 분 지갑에 넣으려면 상품 페이지 주문서에서 「키 받을 이메일」에 그분 메일을 적어 사세요. 다른 메일을 적으면 그 메일의 지갑에 채워져요 — 그 메일의 지갑이 없으면 새 지갑이 생겨요. 지갑 주인이면 대시보드 AI API 화면의 「크레딧 충전」 단추가 같은 상품으로 바로 데려가요.
- 학교는 학교장터(S2B)에서도 사요 — 모델을 정하지 않은 「학교용 AI API 선불 크레딧 이용권」이나, 「제미나이 API 토큰 팩 이용권」 같은 토큰 팩으로 계약해요. 계약 뒤 받으신 입력 링크의 받는 메일 칸(토큰 팩 · 크레딧만 산 계약은 「API 키를 만들 이메일」, 좌석과 같이 산 계약은 「계정 안내 이메일」)에 쓰시던 지갑의 주인 메일을 적어 내면, 내는 순간 같은 지갑에 채워지고 키는 그대로 써요(쓰던 키가 있으면 「크레딧을 넣었어요」 안내 메일만 가요 · 그 메일의 지갑이 없으면 새로 생기고 「키 받기」 링크가 가요). 팩이 둘 이상이면 팩마다 받을 분 메일을 따로 적을 수 있어요 — 비운 팩은 위 메일로 가요. 고객센터에 따로 말씀하실 필요는 없어요.
- 카드로 내시면 결제가 승인되는 대로, 계좌입금은 입금이 확인된 뒤에, 후불은 저희가 주문을 확인하면 결제 전에, 학교장터는 입력 링크를 내는 순간 들어가요. 들어왔는지는 GET /v1/credits 의 purchased_credits 가 늘었는지로 보세요 — 잔액(balance_credits)은 쓰는 만큼 줄어서 충전분이 가려질 수 있어요.
- 차감은 모델과 단가 표에 100만 토큰당 크레딧으로 표시된 차감 단가를 따라요. 한 번에 쓰는 크레딧은 (입력 토큰 × pricing.input_credits_per_mtok + 출력 토큰 × pricing.output_credits_per_mtok) ÷ 100만이고, 단가는 GET /v1/models(키 없이 열려요)에서 읽어요(캐시 · 긴 입력 구간 단가는 「모델과 단가」 장). 이 두 칸은 pricing.rates 의 input_text · output 줄과 같은 값이라 어느 쪽을 읽어도 돼요 — 캐시 단가는 rates 에만 있어요. 예: gpt-4.1-mini(100만 토큰당 입력 367.92 · 출력 1,471.68 크레딧 · 10월 기준)로 1,000 토큰 글에 150 토큰 답이면 약 0.59 크레딧(약 1.2원)이에요 — 단가는 바뀔 수 있으니 GET /v1/models 에서 다시 보세요. 1 크레딧은 부가세 포함 2원어치예요. 캐시 읽기는 입력보다 싸게 계산돼요.
- 토큰 팩(「3.1 Pro 100만 토큰 팩」 같은 상품)은 팩 이름의 모델로 입력 · 출력을 각각 그 토큰 수만큼 쓸 크레딧으로 들어가요 — 그 모델의 (pricing.input_credits_per_mtok + pricing.output_credits_per_mtok) × 백만 단위 토큰 수예요(긴 입력 구간이 아닌 기본 단가로 셈해요). 예: 「3.1 Pro 300만 토큰 팩」 하나는 3 × (1,839.6 + 11,037.63) ≈ 38,632 크레딧이에요(10월 기준 · 정본은 GET /v1/models). 지갑엔 크레딧으로 모여서, 다른 모델을 부르면 그 모델 단가로 줄어요 — 같은 크레딧이면 gemini-3.8-flash 는 입력 · 출력 각 약 930만 토큰, gpt-4.1-mini 는 각 약 2,100만 토큰어치예요.
- 제미나이 토큰 팩으로 산 크레딧은 GPT · 클로드까지 모든 모델을 불러요. 클로드 · GPT 팩으로 산 크레딧은 제미나이(id 가 gemini 로 시작하는 모델)를 뺀 모델을 불러요. 「원포트 AI API 크레딧」 · 「학교용 AI API 선불 크레딧 이용권」처럼 모델을 정하지 않은 크레딧은 모든 모델을 불러요. 지갑 잔액은 하나라서, 제미나이 팩이나 모델을 정하지 않은 크레딧을 넣은 지갑이면 남은 크레딧 전부로 제미나이를 불러요. 내 크레딧이 어느 쪽인지는 키를 붙여 GET /v1/models 를 부르면 응답 맨 바깥 칸(data 옆) credit_scope.label 에 나와요(대시보드 잔액 아래 「이 크레딧으로 부를 수 있는 모델」 줄도 같은 값이에요).
- 생각(추론) 토큰은 출력 단가로 계산돼요. Gemini · Grok 은 응답의 completion_tokens 에 생각한 몫이 안 들어가는데(Gemini 는 total_tokens 에만, Grok 은 completion_tokens_details.reasoning_tokens 에 따로 잡혀요), 벤더가 출력으로 받는 몫이라 저희도 출력으로 빼요 — 그래서 차감이 completion_tokens 로만 셈한 값보다 클 수 있어요.
- Claude 는 캐시 쓰기가 입력보다 비싸게 계산돼요 — 5분 캐시 쓰기는 입력가의 1.25배, cache_control 에 ttl "1h" 를 준 1시간 캐시 쓰기는 입력가의 2배예요. 1시간 몫은 /v1/messages 면 usage.cache_creation.ephemeral_1h_input_tokens, /v1/chat/completions 면 usage.prompt_tokens_details.cache_write_1h_tokens(0 보다 클 때만 와요)로 따로 와요 — cache_write_tokens 는 5분 · 1시간 쓰기를 합친 수예요.
- Claude 에 inference_geo "us"(미국에서만 처리)를 주시면 모든 토큰이 1.1배로 계산돼요. Anthropic 이 매기는 배수 그대로이고, 응답의 usage 가 실제로 그렇게 처리됐다고 알려준 호출에만 붙어요. /v1/messages 로 부를 때만이에요 — /v1/chat/completions 는 이 칸을 빼고 보내요(x-gateway-ignored-params 에 적혀요).
- 스트리밍이 중간에 끊겨도 그때까지 쓴 토큰은 차감돼요.
남은 양 · 쓴 양 보기#
남은 크레딧은 대시보드 AI API 화면(스쿨오더 https://schoolorder.kr/dashboard/api · 오피스오더 https://officeorder.co.kr/dashboard/api) 맨 위에 보여요. 그 아래 누적 충전 · 누적 사용 · 최근 30일(호출 수 포함)도 있어요. 누적 충전은 같은 화면 「충전 내역」 줄의 합이에요(산 것 · 지급 · 잔액 조정은 더하고 환불은 빼요) — 그래서 누적 충전 − 누적 사용이 남은 양과 맞아요(누적 사용은 1 크레딧 아래를 올리고 다른 둘은 버려서 1 크레딧쯤 어긋날 수 있어요). GET /v1/credits 의 purchased_credits 는 환불 · 조정을 빼거나 더하지 않은 누적이라 화면의 누적 충전과 다를 수 있어요. 지갑 주인으로 로그인해야 보여요 — 지갑 주인은 주문서 「키 받을 이메일」로 로그인하는 계정이에요(비웠으면 로그인 여부와 상관없이 주문서의 증빙 받을 이메일이에요 — 대시보드 안에서 낸 주문은 그 주문을 낸 분이에요). 학교장터로 사셨으면 입력 링크에 적은 받는 메일의 계정이에요(토큰 팩 · 크레딧만 산 계약은 「API 키를 만들 이메일」, 좌석과 같이 산 계약은 「계정 안내 이메일」 칸) — 팩마다 받을 분 메일을 따로 적었으면 그 팩은 그분 메일의 지갑에 들어가요. 숫자가 0 이거나 「충전 전」이면 화면의 「내 API 계정」 메일이 지갑 주인 메일인지 먼저 보세요. 코드에서 보실 땐 아래 GET /v1/credits 예요. 잔액이 적어졌을 때 자동으로 가는 메일 · 웹훅은 없어요 — 대시보드 맨 위엔 잔액이 약 3,800 크레딧 이하로 내려가면 「잔액이 얼마 남지 않았어요」 줄이 떠요(이 기준은 바꿀 수 없어요). 원하는 기준으로 보시려면 GET /v1/credits 를 정한 시각에 불러 balance_credits 를 보세요(요금 없음 · 아래 「아침 점검」). 대학 · 기업 지갑은 같은 화면 「사용 기록」(최근 30건)에 「키별 사용량」 칸이 있어 키마다 골라 봐요 — 이 칸이 보이면 정산 원장도 키마다 줄이 남는 지갑이에요. API 키가 하나라도 있어야 이 칸이 떠서, 키를 만들기 전엔 칸이 없어도 학교 지갑이라는 뜻이 아니에요. 「담당자 넘기기」 칸은 학교 지갑과 기관 이름으로 주문해 채운 지갑에 떠요 — 개인 구매가 섞인 지갑엔 없고, 안 보이면 고객센터로 말씀해 주세요. 학교 · 기관 지갑의 담당자가 바뀌면 지금 지갑 주인이 같은 화면 「담당자 넘기기」에 새 담당자 메일을 적어요 — 새 담당자가 그 메일로 로그인해 메일로 받은 링크를 7일 안에 열면 넘어가고, 옛 주인은 팀원으로 남아요. 그사이 다른 길로 지갑 주인이 바뀌었으면 7일 안이어도 그 링크는 만료된 링크로 나오고 넘어가지 않아요 — 지금 지갑 주인께 다시 넘겨 달라고 하세요. 이 칸은 지갑 주인 화면에만 있어서, 주인이 아니면 주인께 부탁하세요. 넘긴 뒤 키가 어떻게 되는지는 「키 관리」 장(https://oneport.kr/docs/reference/keys.md)에 있어요.
- 학교장터 토큰 팩으로 채운 지갑이면 잔액 아래에 산 팩 줄이 있어요.
- 같은 팩만 사셨으면 산 팩과 남은 비율을 보여요 — 「Sonnet 5 100만 토큰 팩 × 10 · 100% 남음」.
- 같은 모델 팩을 크기만 달리 사셨으면 토큰으로 합쳐 보여요 — 「3.1 Pro 400만 토큰 · 80% 남음」.
- 남은 비율은 산 팩 값 대비예요 — 다른 모델을 부르면 그 모델 값만큼 줄어요.
- 토큰 팩 지갑은 위 「잔액이 얼마 남지 않았어요」 줄 대신 산 팩에 맞춰 「잔액 적음」을 띄워요 — 지금 속도로 14일 안에 다 쓰거나(산 지 30일이 안 됐으면 산 뒤의 속도로) 남은 비율이 10% 이하일 때요. 14일 안이면 「지금 속도면 약 N일 뒤에 다 써요」도 함께 떠요.
- 토큰 팩 지갑의 [같은 팩 다시 사기]는 산 팩과 개수를 고른 상품 페이지(여러 팩이면 합본 견적서)를 열어요 — 학교장터 물품번호와 견적서가 거기 있어요. 다 썼을 땐 학교장터로 들어오기까지 며칠 걸릴 수 있어 [카드로 바로 충전]도 같이 보여요.
- 다른 모델 팩을 섞어 사셨으면 값으로 합쳐 보여요 — 「3.1 Pro 100만 토큰 팩 × 1 · Sonnet 5 100만 토큰 팩 × 2 · 합쳐서 68% 남음」.
- 다른 충전이나 무료로 받은 크레딧(가입 · 지급)이 섞이면 남은 양은 안 나오고 산 것만 보여요 — 「산 것 3.1 Pro 100만 토큰 팩 × 1」.
잔액 조회#
curl https://oneport.kr/v1/credits \
-H "Authorization: Bearer $ONEPORT_API_KEY"{
"object": "credit_balance",
"balance_credits": 42350,
"purchased_credits": 50000,
"used_credits": 7650,
"key_prefix": "sk-so-a1b2c3…",
"wallet_id": "wal_q7mzr2kxv4tna6hbe3wy"
}응답 필드
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| balance_credits | 정수 (크레딧) | 지금 남은 크레딧이에요. 1 크레딧 아래는 버려서 보여드려요. 진행 중인 호출이 미리 잡아 둔 몫(예약)은 여기서 안 빠져요 — 호출이 끝나고 정산될 때 줄어요. 그래서 잔액이 남아 보여도 진행 중인 호출이 많으면 402 가 날 수 있어요. |
| purchased_credits | 정수 (크레딧) | 지금까지 충전하신 크레딧이에요(가입 때 받은 무료 크레딧도 들어가요). 계정이 생긴 뒤 누적이라 환불해도 줄지 않고, 매달 채워 드리는 무료 크레딧은 안 들어가요(매달 채우기는 학교·기관에 붙지 않은 개인 지갑만 받아요) — 그래서 purchased_credits − balance_credits 가 used_credits 와 안 맞을 수 있어요(대시보드의 누적 충전은 환불 · 조정까지 반영한 충전 내역의 합이라 이 칸과 달라요). 쓴 양은 used_credits 로 보세요. 스쿨오더 · 오피스오더 · 학교장터 어디서 채우셔도 이 칸에 더해져요 — 충전이 들어왔는지는 이 칸이 늘었는지로 보세요. |
| used_credits | 정수 (크레딧) | 지금까지 실제로 쓴 크레딧이에요. 1 크레딧 아래는 올려 세요 — 조금이라도 썼으면 0 이 아니에요(잔액 · 누적 충전은 버려요 · GET /v1/key 의 used_credits 와 같은 자). 실패한 호출은 여기 안 들어가요(영상은 입력이 안전 기준에 막혀 AI 회사가 값을 매긴 경우만 들어가요). |
| key_prefix | 문자열 | 이 조회에 쓴 키의 앞부분이에요. 키를 여러 개 나눠 쓰실 때 어느 키로 물었는지 확인하는 자리예요. sk-so-AbC123… 처럼 sk-so- 와 그 뒤 6글자에 「…」를 붙인 값이에요 — 점검 스크립트 화면 · 로그에는 키 전체 대신 이 값을 남기세요. |
| wallet_id | 문자열 (wal_ 로 시작) | 이 키가 속한 지갑의 식별자예요. wal_ 로 시작하는 문자열이에요 — 꼴이나 길이에 기대지 말고 같은지만 견주세요. 같은 지갑이면 GET /v1/credits · GET /v1/key · 관리 키의 GET /v1/keys 가 늘 같은 값을 줘서, 키 여러 개가 한 지갑을 쓰는지는 이 값이 같은지로 봐요. 키를 새로 받아도 그대로예요. 저희 안쪽 지갑 번호가 아니고, 이 값으로 그 번호를 되짚을 수도 없어요. |
잔액을 잠깐 못 읽으면 0 으로 답하지 않고 503 api_error 를 드려요. Retry-After: 2 가 붙으니 그만큼 쉬고 다시 부르세요(GET /v1/key 의 503 도 같아요).
키마다 한도 걸기#
- 대시보드 AI API 화면에서 「여러 개 발급」을 열면 만들 개수 · 이름 앞머리 · 키별 월 한도 · 키별 하루 한도 · 「이 날까지 사용」(기한)을 한 번에 넣어요. 기한은 고른 날 다음 날 한국 시간 0시에 닫혀요 — 과제 마지막 날을 고르면 그 뒤로는 안 불려요(기한 지난 키와 키 자리는 「인증」 장). 이름은 「앞머리 1」, 「앞머리 2」…로 붙고(개수를 1 로 두면 번호 없이 앞머리 그대로라, 선생님 이름 키를 한도와 함께 하나씩 만들 수 있어요), 키는 CSV 로 받아요. 「새 키 발급」엔 한도 칸이 없어요(초·중·고 학교 지갑은 쓰임새 칩 [학생 · 선생님]이 더 있고 학생이 기본이에요) — 하나씩 만든 키 · 이미 만든 키는 목록의 「한도 수정」에서 한도와 기한을 넣어요.
- 대시보드 키 목록에도 키마다 「이번 달 사용 / 한도」가 보이고, 하루 한도를 걸었으면 「오늘」 줄도 보여요.
- 키마다 한도를 걸어도 모든 키가 한 지갑의 크레딧을 같이 사용해요 — 지갑이 비면 한도가 남은 키도 402 insufficient_credit 이에요. 월 중간에 만든 키도 날짜로 나누지 않고 그달 한도를 전부 쓸 수 있어요.
- 관리 키는 지갑 주인이 대시보드 AI API 화면 아래 「관리 키」에서 만들어요(지갑마다 5개까지 · 만든 자리에서 한 번만 보여요). 머리글은 Authorization: Bearer sk-som-… 예요. 관리 키로는 GET /v1/credits · GET /v1/key 를 못 불러요(401) — 잔액은 sk-so- 키로 봐요. 스크립트에서 키 목록과 지갑 잔액을 같이 보려면 두 키가 다 필요해요. 두 키가 같은 지갑 것인지는 두 응답 맨 바깥(최상위) 칸 wallet_id 가 같은지로 봐요(아래 「아침 점검」 예시).
- 강좌 몫(group)이 있는 키는 원포트 스페이스 지갑의 키예요. 스페이스 지갑엔 관리 키를 만들 수 없고(대시보드의 「관리 키」는 스쿨오더 · 오피스오더 지갑 것이에요), GET /v1/keys 목록에도 스페이스 강좌 키는 안 나와요. 그래서 관리 키로 본 키 목록과 강좌 키로 본 몫은 서로 다른 지갑의 값일 수 있어요 — 한 스크립트에 섞기 전에 세 문(GET /v1/credits · GET /v1/key · 관리 키의 GET /v1/keys) 응답 맨 바깥(최상위) 칸 wallet_id 가 같은지 보세요. 다르면 다른 지갑이에요(값을 섞어도 오류는 안 나요). 강좌 몫 · 학생 키는 이렇게 봐요 — 강좌 몫은 그 강좌 키로 GET /v1/key 를 불러 group 을 보고, 학생 키마다 쓴 몫은 그 키로 부른 GET /v1/key 의 month.used_credits 예요. 학생별 사용을 한 번에 보려면 스페이스 관리자(행정팀 · 그룹 관리자)가 스페이스 관리 화면 「그룹」 탭의 그룹 카드 「개인 API 키」에서 「학생별 보기」를 눌러요(받았나 · 사용 · 한도 · 마지막 사용 — 보는 이유를 적어야 열리고, 열람 기록이 남아요). 스페이스 학생 키를 한 번에 돌려주는 /v1 문은 아직 없어요.
- 스페이스 강좌 키 · 개인 API 키의 한도는 스페이스 관리자가 정해요. 대시보드 「한도 수정」이나 PATCH /v1/keys/{id} 로는 못 바꿔요(404).
- 스크립트로 하실 땐 관리 키(sk-som-)로 POST /v1/keys 에 {"count": 30, "name_prefix": "과학 동아리", "daily_limit_credits": 250, "monthly_limit_credits": 5000} 처럼 보내요. 이미 있는 키는 PATCH /v1/keys/{id} 로 바꿔요 — 보낸 칸만 바뀌고, 한도 칸에 null 을 보내면 그 한도를 지워요. 대시보드엔 키 이름을 바꾸는 자리가 없어서 이름은 PATCH 로만 바꿔요. 칸 이름은 _credits 까지 그대로 적어요 — 다른 이름은 400 이에요. 키엔 월 · 하루 한도와 기한(expires_on)만 걸려요 — 과제 총액처럼 다시 채워지지 않는 누적 상한은 없으니, 연구실 배정액은 정산 원장 CSV 의 누적 차감으로 맞대 보세요.
- 하루 한도는 월 한도보다 클 수 없어요. 하루 한도는 한국 시간 0시에, 월 한도는 매달 1일 한국 시간 0시에 다시 열려요.
- 키 여러 개의 남은 몫은 관리 키로 GET /v1/keys 를 한 번 부르면 돼요(요금 없음) — 줄마다 daily_limit_credits · day_used_credits · monthly_limit_credits · month_used_credits 가 오고, 남은 몫은 한도에서 쓴 몫을 빼면 돼요. 키를 하나씩 모아 부를 필요가 없어요. 하루 한도를 안 건 키도 day_used_credits 는 오늘 쓴 몫을 세요. 목록엔 켜진 키만 오고(끈 키는 빠져요) 한 번에 100줄까지예요(?limit= 최대 500 · ?offset= — has_more 가 true 면 이어 읽어요). 응답은 {"object": "list", "data": [ … ], "total", "has_more", "room", "cap", "wallet_id"} 이고(wallet_id 는 줄마다가 아니라 봉투 맨 바깥에 하나예요), 줄마다 id · name · key_prefix · audience(student · teacher · null — 쓰임새를 나누지 않는 지갑의 키는 null) · expires_at · usable_until · created_at · last_used_at 도 와요. 학생 키만 보려면 audience 가 "student" 인 줄을 고르세요. 한도를 안 건 키는 monthly_limit_credits · daily_limit_credits 가 null 이에요. 사람의 채팅 키 · 스페이스 강좌 키는 목록에 없어요.
- 키 하나는 그 키로 GET /v1/key 를 불러요. 예: "day": {"limit_credits": 250, "used_credits": 120, "remaining_credits": 130, "resets_at": "2026-10-27T15:00:00.000Z"} — resets_at 은 UTC 시각이라 이 값은 한국 시간 28일 0시예요. 응답 칸 전체(audience · usable_until · month 에만 있는 held_credits 등)는 「남은 한도」 장(https://oneport.kr/docs/reference/key.md)에 있어요.
- group 은 원포트 스페이스 지갑에서 관리자가 만든 반 · 강좌 · 학과 · 기수 묶음의 몫이에요. 스페이스가 아닌 지갑(스쿨오더 · 오피스오더 대시보드의 지갑)의 키는 늘 null 이에요. 칸은 {"name", "mode", "closed", "closed_reason", "limit_credits", "used_credits", "remaining_credits", "resets_at", "starts_on", "ends_on"} 예요(closed_reason · starts_on · ends_on 은 2026-11-01 부터 — 뜻은 「남은 한도」 장 group 칸). mode 가 "monthly" 면 resets_at 이 다음 달 1일 한국 시간 0시(그때 다시 채워져요)이고, "total" 이면 누적이라 null 이에요(다시 안 채워져요). 강좌에 상한이 없으면 limit_credits · remaining_credits 가 null 이에요 — 그땐 지갑 잔액까지 써요.
- 만든 키의 원문은 201 응답 data 줄마다 key 칸에 와요 — 이 응답에만 오니 바로 저장하세요. id 는 PATCH /v1/keys/{id} 에 쓰는 값이에요. 이름을 사람마다 다르게 하려면 count 없이 name 에 이름을 넣어 한 번씩 보내거나, 만든 뒤 PATCH 로 name 을 바꿔요.
- 키는 지갑의 키 자리만큼 만들어요. 따로 정하지 않은 지갑은 켜진 키가 모두 50개까지예요(사람의 채팅 키 · 아직 채팅 키가 없는 팀 자리도 같은 자리를 써요). 남은 자리는 관리 키로 GET /v1/keys 의 room 이에요. 모자라면 POST /v1/keys 는 하나도 만들지 않고 400(code key_room_exceeded)으로 알려 줘요 — 자리 셈은 「키 관리」 장에 있어요.
- 지난 날짜 · 기간별 사용 내역은 API 로 주지 않아요(키마다 이번 달 · 오늘 쓴 몫은 GET /v1/keys 의 month_used_credits · day_used_credits 로 와요). 대시보드 AI API 화면(스쿨오더 https://schoolorder.kr/dashboard/api · 오피스오더 https://officeorder.co.kr/dashboard/api) 「사용 기록」 아래의 「정산 원장 받기 (CSV)」가 키 × 한국 날짜 × 모델 줄로 내려 줘요(지갑 주인으로 로그인해야 그 지갑 줄이 나와요 — 팀원으로 로그인하면 받을 수 없고, 주인도 팀원도 아닌 계정이면 404 「계정을 찾지 못했어요.」예요. 「감사 로그 받기」도 같아요). 파일 주소에 ?from=YYYY-MM-DD&to=YYYY-MM-DD 를 붙여 열면 그 기간만 받아요 — 예: https://schoolorder.kr/dashboard/api/settlement.csv?from=2026-03-01&to=2026-10-31(대시보드 화면 주소 /dashboard/api 에 붙이면 파일이 안 받아져요). 이때는 인정 기간과 상관없이 그 날짜의 줄만 읽어요(줄마다 「인정」 · 「기간 밖」 표시는 그대로예요). 줄의 날짜는 요청을 받은 한국 시각이에요 — 끝 날 자정 직전에 보낸 호출은 답이 다음 날 끝나도 끝 날 줄에 들어가요. 끝 날 줄은 그날 보낸 호출이 다 끝나야 채워져요 — 닫힌 기간 파일은 끝 날 다음 날 아침에 받으면 돼요 — 글 · 그림 · 소리 · 임베딩 호출은 길어야 약 14분 안에 끝나서 그때 줄이 다 채워져요(예: 일요일까지의 주간 파일은 월요일 아침). 영상 · 작업은 끝나는 대로 요청한 날 줄에 더해지니, 쓰셨으면 그 작업이 끝난 뒤 받으세요. 2026-10-29 까지(이 바뀜 전) 사용은 답이 끝난 시각으로 날짜가 잡혀 있을 수 있어서, 그 기간을 맞출 땐 to 를 하루 늘려 받아 끝 날 다음 날 줄도 같이 보세요(예: 9월분은 ?from=2026-09-01&to=2026-10-01 — to 날까지만 받은 파일엔 다음 날 줄이 없어요). 달력에 없는 날(예: 2026-09-31)이나 from 이 to 보다 늦으면 400 이에요. ?from= 은 얼마나 옛날 날짜든 받아요 — 오래전 사용도 같은 꼴의 줄로 들어가요. 주소 그대로 받으면 최근 180일이 와요(사업비 인정 기간이 적힌 지갑은 그 기간 시작 31일 전부터 오늘까지 — 기간 밖에 쓴 몫도 「기간 밖」으로 표시해 같이 넣으려고 넓게 읽어요 · 그 시작 31일 전이 아직 안 왔으면 위 기본 그대로예요 — 2026-11-01 부터, 예전엔 400 이었어요). 「감사 로그 받기」는 주소 그대로 받으면 이번 달만 와요 — 과제 기간은 같은 꼴로 붙여 받아요(예: https://schoolorder.kr/dashboard/api/audit.csv?from=2026-03-01&to=2026-10-31). 감사 로그는 한 파일에 5,000줄까지라, 넘으면 이른 날 기록이 빠지고 끝에 「⚠️ 상한에 걸려 잘렸어요 — 기간을 좁혀 다시 받아주세요」 줄이 붙어요 — 그 줄이 보이면 달마다 나눠 받으세요(정산 원장처럼 나눠 받는 화면은 안 떠요). 기록을 잠깐 못 읽으면 잘린 파일 대신 「사용 기록을 읽지 못했어요. 잠시 뒤 다시 받아 주세요.」가 와요(2026-11-01 부터) — 기간은 좁히지 마세요. 인정 기간을 지갑에 적는 법은 이 장 첫 목록의 재원 줄이에요. 인정 기간 · 재원 이름은 지갑마다 하나라, 연구실마다 과제 기간이 다르면 J 칸은 지갑에 적힌 기간으로만 찍혀요 — 과제별로 맞추시려면 A 칸 날짜로 직접 거르거나, 과제마다 다른 메일로 사서 지갑을 나누세요. 사용 기록이 2만 건을 넘으면 파일 대신 나눠 받는 링크 화면이 떠요 — 여러 달이면 달마다, 한 달 안이면 7일씩, 7일 안이면 날마다 나눠요(하루 기록만으로 넘으면 고객센터로 말씀해 주세요). 주간 · 월간 보고 숫자는 이 파일로 받으세요. API 로 날마다 적으시려면 GET /v1/keys 의 day_used_credits 를 한국 시간 자정 직전(예: 23시 55분)에 읽어 두세요 — 0시가 지나면 0 으로 돌아가 전날 몫을 다시 못 읽고, 그날 끈 키는 목록에서 빠져 그 몫도 같이 빠져요. day_used_credits · month_used_credits 와 잔액은 답이 끝난 때 움직여서, 자정을 걸친 호출은 그쪽에선 다음 날 몫이라 CSV 와 하루 갈릴 수 있어요.
- 기간 중 충전 · 지급 · 환불 · 조정은 같은 화면 「충전 내역」에서 봐요 — 날짜 · 내역 · 주문 번호 · 크레딧이 최근 50건까지 보여요. 학교장터로 채운 줄은 내역이 「학교장터 계약 충전」이고 주문 번호가 S2B- 로 시작해요 — 팩 이름 · 개수는 잔액 아래 팩 줄에 있어요. 토큰 팩은 입력 링크를 낸 그때의 단가로 들어갈 크레딧이 정해져서, 뒤에 단가가 바뀌어도 들어간 크레딧은 그대로예요(부를 때는 그때 단가로 사용해요). 기초 · 기말 잔액은 파일에도 API 에도 없어요. 기간 경계에 GET /v1/credits 의 balance_credits 를 적어 두거나, 지금 잔액에서 거꾸로 셈해요 — 그 날 뒤에 쓴 몫(다음 날부터 오늘까지 받은 정산 원장 CSV 의 끝 합계 두 줄을 더한 값)을 더하고, 그 날 뒤의 「충전 내역」 줄을 빼요(환불 · 조정은 적힌 부호 그대로). 잔액은 1 크레딧 아래를 버리고 합계는 올린 값이라 몇 크레딧 어긋날 수 있어요.
- 파일은 엑셀에서 바로 열려요(한글이 안 깨져요). 맨 위는 # 줄 다섯 — ① 재원 이름(안 적힌 지갑은 「AI API 사용량 원장」) ② 사업비 인정 사용기간(시작 · ~ · 끝, 안 적혔으면 (미지정)) ③ 뽑은 시각(KST) ④ 귀속 기준(요청 발생 시각) ⑤ 금액은 쓴 크레딧이라는 말(1 크레딧 = 부가세 포함 2원) — 과 빈 줄 하나라 칸 이름은 엑셀 7행이에요. 「(팀 채팅)」이나 「(지갑 전체)」 줄이 하나라도 있는 파일(학교 지갑 · 아래)은 그 까닭을 적은 # 줄이 하나 더 붙어 8행이에요 — 지갑 주인만 팀 채팅을 썼어도 붙어요. 칸은 A 사용일(KST) · B 키 · C 키 이름 · D 모델 · E 벤더 · F 호출수 · G 입력토큰 · H 출력토큰 · I 차감(크레딧) · J 사업비 인정이고(사용일은 2026-10-27 꼴 · 호출수 · 토큰 · 차감 칸은 쉼표 없는 수), 사업비 인정 칸은 「인정」 아니면 「기간 밖」이에요(기간이 안 적힌 지갑은 모든 줄이 「인정」). 호출수는 모델 회사로 보낸 호출을 다 세요 — 시간 초과 · 모델 회사 오류로 차감 0 으로 끝난 호출도 1이라, 실패가 있던 날은 성공한 수보다 커요. 초로 값을 매기는 받아쓰기(whisper-1 등) 줄은 입력 · 출력토큰이 0 이고 길이(초)는 이 파일에 없어요 — 길이가 필요하면 응답 usage 를 기록하세요. 입력토큰은 캐시 몫을 뺀 나머지이고 차감엔 캐시 쓰기 · 읽기 값까지 들어 있어서, 입력 · 출력 토큰 × 단가와 다를 수 있어요 — 토큰별로 맞추시려면 응답 usage 를 기록하세요. 끝에는 빈 줄 하나 뒤에 「# 인정기간 안 합계(크레딧)」 · 「# 인정기간 밖 합계(크레딧)」 두 줄이 오고, 값은 B 칸에 와요 — 이 두 줄은 늘 붙어요(기간이 안 적힌 지갑이면 「밖 합계」가 0 이에요). 차감은 줄마다 1 크레딧 아래를 올려 적어서, 줄을 더하면 끝의 합계(원래 금액을 더한 뒤 한 번 올린 값)보다 조금 클 수 있어요 — 연구실별로 나눠 더한 값도 그래요. 정산서 총액은 끝의 합계 줄을 쓰세요. 피벗 · 수식 전엔 칸 이름 줄 위의 머리 줄과 끝 세 줄(빈 줄 포함)을 지우세요. 스크립트로 읽으실 땐 utf-8-sig 로 열고 「사용일(KST)」로 시작하는 칸 이름 줄부터 읽은 뒤, 첫 칸이 # 로 시작하는 끝 줄과 빈 줄을 빼세요 — pandas 의 comment="#" 는 키 이름에 # 이 든 줄도 중간부터 잘라서 쓰지 마세요.
- 두 파일(정산 원장 · 「감사 로그 받기」) 모두 값에 쉼표 · 따옴표 · 줄바꿈이 들면 따옴표로 감싸고, 글 칸이 = · + · - · @ 로 시작하면 엑셀이 수식으로 읽지 않게 앞에 ' 를 붙여요(키 이름 등 · 숫자 칸은 그대로) — 스크립트로 맞춰 볼 땐 그 ' 를 떼고 견주세요. 감사 로그는 호출마다 한 줄이지만, 90일이 지난 날은 날짜별 요약으로 줄여 둬서 그날은 키 × 모델마다 한 줄로 와요 — 시각 칸에 「YYYY-MM-DD 날짜별 요약 · 호출 N건」이 적히고 토큰 · 금액은 그날 합이에요. 그런 줄이 있으면 맨 끝에 「사용 기록은 90일 뒤 날짜별 요약으로 줄여 5년 둬요.」 한 줄이 붙어요. 기록을 잠깐 못 읽으면 파일 대신 503 「사용 기록을 읽지 못했어요. 잠시 뒤 다시 받아 주세요.」가 와요.
- 키 이름은 바꿀 수 있어서, 키별로 묶을 땐 「키」 칸(키 앞부분)으로 묶는 게 안전해요. 「키」 칸은 sk-so-AbC123… 처럼 sk-so- 와 그 뒤 6글자, 말줄임표 「…」 한 글자예요(대시보드 키 목록의 앞부분과 같아요) — 마침표 세 개로 치지 말고 파일에서 그대로 복사해 짝 표에 넣으세요. 키를 「새로 받기」로 바꾸면 이름은 같아도 「키」 칸이 새 값이 되니 짝 표에 새 키도 더하세요 — 새로 받은 키는 이번 달 · 오늘 쓴 몫을 이어받아 GET /v1/keys 엔 새 키 줄 하나로 보이고, CSV 엔 옛 앞부분 줄과 새 앞부분 줄로 나뉘어요. 관리 키 GET /v1/keys 줄의 key_prefix 도 이 「키」 칸과 같은 값이라, 짝 표 하나로 API 목록과 CSV 를 같이 묶어요.
- 대학 · 기업 지갑으로 등록되지 않은 지갑은 학교 지갑으로 봐요(오피스오더에서 회사 · 기관으로 산 크레딧은 처음부터 기업 지갑으로 열려 키마다 줄이 남아요 — 키 받을 메일에 쓰던 학교 지갑이 이미 있으면 저희가 확인하고 넣어 드려요. 그 밖의 지갑은 저희가 따로 등록하지 않으면 학교 지갑이에요) — 학교 지갑은 이 파일에서 사람을 가리지 않아요. 팀 채팅으로 쓴 몫은 키 칸 「(팀 채팅)」 · 키 이름 「사람 구분 없음」로 모여요 — 사람만 합치고 줄은 날짜 × 모델마다 하나씩이며, 지갑 주인이 채팅으로 쓴 몫도 여기 들어가요. 그 파일에서 주인 말고 팀 채팅을 쓴 분이 1~2명이면 API 키 줄까지 「(지갑 전체)」 · 「채팅·API 합산」로 모여요(팀 장부를 잠깐 못 읽은 날도 그렇게 모여요). 키별로 나눠 보시려면 선생님마다 API 키를 따로 만들어 드리세요 — 팀 채팅을 쓴 분이 0명이거나 3명 이상이면 API 키 줄이 키마다 남아요. 이렇게 모인 줄이 하나라도 있는 파일은 머리에 그 까닭을 적은 # 줄이 하나 더 붙어요. 대학 · 연구실 지갑인데 키 줄이 「(지갑 전체)」로 모였으면 고객센터에 대학 지갑으로 바꿔 달라고 말씀해 주세요 — 줄 모으기는 받을 때마다 그때 지갑 종류로 해서, 바꾼 뒤엔 지난 기간 파일도 다시 받으면 키마다 줄이 나뉘어요. 대학에 붙은 대학 지갑이면 같은 화면 「본부·사업단에 낼 것」에서 위탁·국외이전 명세 · 품의용 사양·금액 명세 · 모델별 토큰표를 받아요.
- 쓰지 않는 키(퇴사 · 졸업)는 관리 키로 DELETE /v1/keys/{id} 를 부르거나 대시보드 키 목록의 「폐기」로 꺼요 — 되돌릴 수 없고, 그 자리는 바로 비어요.
- 월 한도는 이 요청의 최대 몫에 같은 키로 아직 끝나지 않은 호출들의 최대 몫까지 더해 미리 맞대 봐요(앞 호출이 끝나 정산되는 순간과 겹치면 호출 하나 몫쯤 넘을 수 있어요 — 「남은 한도」 장). 하루 한도는 이미 정산된 몫만 봐서, 닿기 전에 보낸 호출(동시에 보낸 것 · 앞 호출 정산 전 몇 초 사이에 보낸 것 포함)은 다 지나가요 — 그만큼 넘을 수 있어요. 넘친 몫도 쓴 몫으로 세서 다음 호출이 막혀요. 예산을 빠듯하게 잡으셨다면 한도를 조금 낮게 거세요. 칸 전체와 응답 모양은 「키 관리」 장(https://oneport.kr/docs/reference/keys.md)에 있어요.
아침 점검 — 잔액과 키별 남은 몫을 한 번에#
날마다 아침에 지갑 잔액과 키마다 이번 달 남은 몫을 한 번에 보는 예시예요. sk-so- 키(잔액)와 관리 키(키 목록)를 같이 써요. 그래서 먼저 두 응답 맨 바깥(최상위) 칸 wallet_id 가 같은지 보고, 다르면 멈춰요 — 다른 지갑의 키를 넣어도 오류는 안 나고 엉뚱한 값만 찍혀요. 키 목록은 한 번에 500줄까지라 has_more 가 false 가 될 때까지 offset 을 늘려 이어 읽어요 — 읽는 사이 키가 생기면 줄이 밀려 겹칠 수 있어서 id 로 한 번만 세요. 두 문 다 요금이 안 붙어요. 스페이스 강좌 키는 관리 키 목록에 안 나와서 이 예시로는 못 봐요(위 목록).
import os, requests
BASE = "https://oneport.kr/v1"
key = {"Authorization": f"Bearer {os.environ['ONEPORT_API_KEY']}"} # sk-so- 키 — 지갑 잔액
admin = {"Authorization": f"Bearer {os.environ['ONEPORT_MANAGEMENT_KEY']}"} # sk-som- 관리 키 — 키 목록
def get(path, headers, **params):
r = requests.get(f"{BASE}{path}", headers=headers, params=params, timeout=30)
if r.status_code != 200:
raise SystemExit(r.json()["error"]["message"]) # 401 이면 이유(두 키를 서로 바꿔 넣었거나 꺼진 키)
return r.json()
c = get("/credits", key)
rows, offset = {}, 0
while True: # 키 목록은 한 번에 500줄까지 — has_more 가 false 가 될 때까지 이어 읽어요
k = get("/keys", admin, limit=500, offset=offset)
if c["wallet_id"] != k["wallet_id"]:
raise SystemExit("두 키가 다른 지갑이에요 — 같은 지갑의 sk-so- 키와 관리 키를 넣어 주세요.")
for row in k["data"]:
rows[row["id"]] = row # 읽는 사이 줄이 밀려 겹쳐도 한 번만
if not k["has_more"]:
break
offset += len(k["data"])
print("지갑 잔액:", c["balance_credits"])
for row in rows.values():
limit = row["monthly_limit_credits"]
left = None if limit is None else max(0, limit - row["month_used_credits"])
print(row["name"], "이번 달 남은 몫:", left) # 한도가 없는 키는 None — 지갑 잔액까지 써요const BASE = "https://oneport.kr/v1";
const key = { Authorization: `Bearer ${process.env.ONEPORT_API_KEY}` }; // sk-so- 키 — 지갑 잔액
const admin = { Authorization: `Bearer ${process.env.ONEPORT_MANAGEMENT_KEY}` }; // sk-som- 관리 키 — 키 목록
async function get(path: string, headers: Record<string, string>) {
const r = await fetch(`${BASE}${path}`, { headers });
if (!r.ok) throw new Error((await r.json()).error.message); // 401 이면 이유(두 키를 서로 바꿔 넣었거나 꺼진 키)
return r.json();
}
const c = await get("/credits", key);
const rows = new Map<string, any>();
for (let offset = 0; ; ) { // 키 목록은 한 번에 500줄까지 — has_more 가 false 가 될 때까지 이어 읽어요
const k = await get(`/keys?limit=500&offset=${offset}`, admin);
if (c.wallet_id !== k.wallet_id) throw new Error("두 키가 다른 지갑이에요 — 같은 지갑의 sk-so- 키와 관리 키를 넣어 주세요.");
for (const row of k.data) rows.set(row.id, row); // 읽는 사이 줄이 밀려 겹쳐도 한 번만
if (!k.has_more) break;
offset += k.data.length;
}
console.log("지갑 잔액:", c.balance_credits);
for (const row of rows.values()) {
const limit = row.monthly_limit_credits;
console.log(row.name, "이번 달 남은 몫:", limit === null ? null : Math.max(0, limit - row.month_used_credits)); // 한도가 없는 키는 null
}무엇이 언제 빠지나요#
- 부르기 전 — 이 요청이 최대로 쓸 금액을 미리 잡아둬요(예약). 잔액이 그보다 적으면 벤더로 보내지 않고 402 를 드려요. 잔액이 최소치 아래면 402 below_minimum_balance 라 충전해야 풀려요(최소치는 「남은 한도」 장).
- 호출 한 번 값은 글 문 · 영상 응답의 usage.cost_credits, 읽어주기는 머리글 x-gateway-cost-credits 로 와요 — 그림 · 받아쓰기 · 임베딩 응답엔 없어서 GET /v1/models 단가로 셈해요.
- 끝난 뒤 — 벤더가 알려준 실제 사용량으로 정산해요. 예약이 실제보다 컸으면 남는 만큼 그대로 돌아와요. 정산은 답을 보낸 뒤 따로 돌아요 — 글 문 셋(/v1/chat/completions · /v1/messages · /v1/responses)과 받아쓰기(/v1/audio/transcriptions)가 같아서, 답 직후의 /v1/credits · /v1/key 는 몇 초 뒤에 다시 보세요. 받아쓰기는 연결이 끊겨도 저희 쪽은 끝까지 돌아요(길어야 2분) — 끊기면 2분쯤 기다렸다가 잔액과 견줘 보고, 줄었으면 이미 사용한 거라 다시 보내면 한 번 더 사용해요(아래 「받아쓰기는 이렇게 빠져요」).
- 실패하면 — 예약이 통째로 풀려요. 실패한 호출로는 돈이 안 나가요. 다만 영상은 입력한 내용이 AI 회사의 안전 기준에 막혀 AI 회사가 값을 매기면 그만큼 빠져요.
- 키 한도에 막히면 — 429 key_limit_exceeded 예요. error.reason 이 key_day_limit 이면 하루 한도라 이미 쓴 몫만 봐서, 출력 상한을 줄여도 같고 한국 시간 0시에 풀려요. key_month_limit 이면 이번 달 한도라 「쓴 몫 + 이 요청이 최대로 쓸 몫」으로 재서 남은 몫이 있어도 막힐 수 있고, max_tokens(/v1/responses 는 max_output_tokens)를 줄이면 지나갈 수 있어요 — 안 적으면 어느 글 문이든 답 하나를 8,192 토큰으로 잡아요. 대시보드에서 한도를 올리면 바로 풀려요. 둘 다 x-should-retry: false 가 붙고, 시각은 error.resets_at 에 와요. held_by_others 면 같은 키로 아직 끝나지 않은 호출 몫까지 더해 넘은 거라 Retry-After(5초) 뒤 그대로 다시 보내요(갈래 전체는 「에러」 장).
- 모델이 답을 거절하면 — 실패가 아니라서, 답 글이 없어도 모델이 읽은 입력과 답을 준비하며 쓴 몫이 벤더가 알린 사용량대로 빠져요. Claude 의 거절은 finish_reason 이 content_filter 로 와요(/v1/messages 는 stop_reason 이 refusal).
받아쓰기는 이렇게 빠져요#
- 받아쓰기(/v1/audio/transcriptions)는 파일 하나 4,000,000바이트(4MB)까지, 한 번 부를 때 2분 안(모델 회사 몫 100초)이에요. 크기를 넘으면 413 invalid_request_error, 시간을 넘기면 504 upstream_error 에 x-should-retry: false 예요 — 긴 녹음은 몇 분씩 시간으로 잘라 보내요. 요청 전체가 4.5MB 를 넘으면 저희 앞단에서 text/plain 413(FUNCTION_PAYLOAD_TOO_LARGE)으로 끊겨요 — JSON 봉투가 아니라서 error.type 이 없고 request-id 머리글도 없으니 상태 413 으로 가르세요.
- 부르기 전엔 길이를 몰라서, 미리 잡는 몫은 WAV(PCM)면 잰 길이, 그 밖의 파일은 1,000바이트를 1초로 어림해요 — 32kbps mp3 면 실제 길이의 4배, 64kbps 면 8배예요. 그래서 WAV 가 아니면 402 hold_exceeds_balance · 월 한도 429 는 재생 시간이 아니라 파일 크기로 재요 — 더 짧게 잘라 크기를 줄이면 풀려요. 끝나면 모델 회사가 알린 길이(gpt-4o 계열은 토큰)로 정산하고, 남은 몫은 돌아와요 — 정산은 잡은 몫을 넘지 않아요(2026-10-31 부터).
- 받아쓰기 응답엔 글 문의 usage.cost_credits 가 없어요. 초로 값을 매기는 모델(whisper-1 등 · GET /v1/models 의 pricing.rates 에서 dimension "seconds" · unit "second" 인 줄)은 응답 usage.seconds × 그 줄의 credits 예요 — whisper-1 verbose_json 에 usage 가 없으면 최상위 duration 을 초로 써요. gpt-4o 계열은 토큰 × 단가로 셈해요. usage 는 json · verbose_json 으로 받았을 때만 와요(자세한 셈은 「받아쓰기」 장).
- 응답을 받기 전에 연결이 끊겨도 저희 쪽 받아쓰기는 끝까지 돌아요(길어야 2분). 손님이 끊어도 그 조각 값은 빠지니, 읽기 시간 제한은 2분보다 넉넉히 두세요. openai SDK 는 연결이 끊기면 같은 조각을 스스로 다시 보내니(SDK 동작) 이 문에선 Python max_retries=0 · Node maxRetries: 0 으로 두고 직접 가르세요. 정산은 답을 보낸 뒤 따로 돌아서, 차감이 늦게는 2분쯤 뒤에 보여요 — 끊기면 2분쯤 기다렸다가, 조각을 보내기 직전에 읽어 둔 GET /v1/credits 의 balance_credits 와 견줘 보세요. 그보다 일찍 보고 그대로라고 해서 실행되지 않은 게 아니에요. 줄었으면 그 조각은 이미 사용한 거예요. 같은 지갑을 다른 분도 쓰면 잔액엔 그분 사용도 섞이니, 그 키의 GET /v1/key 의 month.used_credits 도 보내기 전 값과 견줘 보세요. 잔액은 정수 크레딧(내림)이고 month.used_credits 는 올린 정수라, 1 크레딧이 안 되는 짧은 조각은 써도 두 값이 그대로일 수 있어요 — 그대로라는 것만으로 안 쓰였다고 보지 마세요. 이 문엔 끊긴 뒤 받아쓴 글을 되찾는 조회 길(Idempotency-Key · 상태 조회 주소)이 없어서, 같은 조각을 다시 보내면 한 번 더 사용해요 — 그래서 조각은 몇 분으로 작게 두세요(끊겨도 다시 보낼 몫이 작아요).
- 모델 회사로 보낸 뒤 실패한 받아쓰기(시간 초과 · 모델 회사 오류)는 요금이 안 붙지만, 정산 원장 CSV 에는 차감 0 인 줄로 남아 호출수 1 로 세요 — 그래서 실패가 있던 날은 호출수가 성공한 조각 수보다 커요. 초로 값을 매기는 모델(whisper-1 등)의 줄은 입력 · 출력토큰이 0 이고 길이(초)는 그 파일에 없어요 — 길이가 필요하면 응답 usage 를 기록해 두세요. 보내기 전에 막힌 실패(413 · 400 · 402 · 한도 429)는 줄이 안 남아요.
- 이 문의 422 는 모델 회사가 값을 거절한 것(type invalid_request_error)이라, 다시 보내지 말라는 422 upstream_execution_unconfirmed 와 달라요 — 문장대로 고쳐서 보내요. 402 held_by_others · 429 rate_limit_error · 502 upstream_error 엔 Retry-After 가 없어요. 503 api_error 는 모델 정보를 잠깐 못 읽었거나 저희 쪽 사정으로 모델 회사가 받지 않았을 때(error.reason provider_unavailable)만 Retry-After: 2 가 와요. 없으면 몇 초 쉬고(402 held_by_others 는 5초 · 503 은 2초쯤 — 다른 문이 Retry-After 로 주는 값이에요) 같은 조각을 그대로 다시 보내요(실패는 요금이 안 붙어요).
충전과 환불#
크레딧은 쓰기 전에 사 두는 방식이에요. 원화로 결제하고, 학교·기관은 주문서에서 「납품 후 결제(후불)」도 고를 수 있어요. 세금계산서는 계좌입금 주문의 주문서에서 고르면 적어 주신 메일로 발행해요(사업자등록번호나 고유번호가 필요해요). 후불은 주문서에서 정산 방법도 같이 골라요(계좌입금 · 주문서에 「카드 정산」이 보이면 카드도) — 세금계산서가 필요하면 계좌입금을 고르세요. 카드로 내신 주문은(후불을 카드로 정산하셔도) 카드 매출전표가 증빙이라 세금계산서 · 현금영수증을 고르지 않아요. 후불 · 계좌입금에 세금계산서를 고르시면 주문서가 작성일도 물어요. 발행은 납품을 확인한 뒤 담당자가 해요. 다른 서류는 고객센터를 거치지 않고 받아요 — 견적서는 상품 페이지에서 옵션을 고르면 직인이 찍힌 장이 바로 나오고, 주문한 뒤엔 주문 화면(「주문 조회·서류 출력」 — 스쿨오더 https://schoolorder.kr/store/orders · 오피스오더 https://officeorder.co.kr/store/orders)의 서류 칸에서 청구서(계좌입금 주문 — 지출 서류용 · 입금 전에도 열려요) · 거래명세서 · 주문내역서(결제가 확인되면 · 후불은 납품 뒤) · 카드 매출전표(카드 주문) · 사업자등록증을 열어요(서류마다 쓰는 자리는 https://oneport.kr/buy). 학교장터로 계약하셨으면 입력 링크에 세금계산서 칸(「고유번호」 · 「계산서 받을 메일」)이 있어요 — 계좌입금 계약이면 꼭 적어 내요(납품 뒤 그 메일로 끊어 드려요). 카드 계약이거나 학교 정보를 이미 받았으면 이 칸이 안 보여요. 개인 구매는 현금영수증을 받으실 수 있어요. 국고·사업비 구매: 구매일과 관계없이 계약서에 따라 환불합니다. 2026년 10월 1일까지 구매: 위 계약 대상 외에는 남은 크레딧을 공제 없이 환불합니다. 이후 구매는 아래 기준입니다. 사업용 구매: 현금 환불은 제공하지 않으며, 크레딧은 만료 없이 사용합니다. 개인·학교·공공기관 구매: 받으신 날부터 7일 이내의 미사용 크레딧은 공제 없이 환불합니다. 개인 구매: 결제 후 14일 이내이고 사용량이 30% 미만이면 쓰지 않은 크레딧의 대금을 공제 없이 환불합니다. 앞의 공제 없는 환불 기준에 해당하지 않으면 남은 잔액의 10%를 공제합니다. 학교·공공기관 구매: 7일이 지나면 남은 잔액의 10%를 공제합니다. 학교 · 기관 구매는 계약서에 남은 잔액 처리를 정했으면 그 계약이 먼저예요 — 위 학교·공공기관 줄은 계약에 정함이 없을 때고, 학교장터로 맺은 계약은 그 계약 조건(결제 방법 · 검수 · 지급)이 약관보다 먼저예요. 상행위가 아닌 학교·공공기관이 스스로 쓰려고 산 크레딧은 사업용이 아니에요 — 7일 안이면 그대로 돌려드려요. 7일은 주문 확인서를 받은 날과 크레딧이 지갑에 들어간 날 가운데 늦은 날부터 세요. 돌려드리는 돈은 결제마다 「낸 돈 × 그 결제로 받은 크레딧 가운데 안 쓴 크레딧 ÷ 그 결제로 받은 크레딧」이고, 무료로 받은 크레딧을 먼저 쓴 것으로 보고, 산 크레딧은 먼저 들어온 결제부터 쓴 것으로 봐요. 10%를 빼는 경우엔 결제마다 이렇게 셈한 금액에서 빼요 — 그래서 잔액 × 2원과 다를 수 있어요. 환불은 대금을 낸 주문자가 요청하고, 결제한 방법으로 돌려드리는 게 원칙이에요(계좌입금은 알려 주신 계좌로). 환불 · 세금계산서는 고객센터로 말씀해 주세요 — admin@schoolorder.kr · 010-7776-8166 · 평일 09:30–17:30(오피스오더에서 사셨으면 admin@officeorder.co.kr). 그리고 학교회계에는 회계연도 독립의 원칙이 있어 과다한 이월이 지적 사유가 될 수 있으니, 연말에 한꺼번에 많이 사기 전에 그 해에 쓸 만큼인지 먼저 따져 보세요.