내부 대시보드의 API 비용이 공급자 사용량보다 높다면, 가격표를 바꾸기 전에 출력 합계에 추론 토큰을 한 번 더 더했는지 확인하세요. OpenAI와 Claude는 추론을 포함한 출력 합계를 보고합니다. 반면 Gemini의 원래 generateContent 응답에서는 후보 출력과 사고 과정의 토큰 수를 별도 필드로 보고하므로 두 값을 합쳐야 합니다.
같은 reasoning이라는 이름이 등장해도 합산 규칙은 같지 않습니다. 이 글은 2026년 9월 7일 확인한 공식 문서에 따라 일반 텍스트 요청의 출력 토큰을 검산하는 방법을 설명합니다. 구독 요금이나 모델 추천이 아니라, 이미 받은 usage를 잘못 집계하지 않는 것이 목표입니다.
먼저 확인할 것은 모델명이 아니라 응답 형식입니다
아래 표에서 ‘계산할 출력 토큰’은 해당 요청의 출력 단가를 적용할 토큰 수입니다. 입력, 캐시, 도구 등 다른 비용을 포함한 청구서 전체 금액은 아닙니다.
| 실제로 호출한 API | 계산할 출력 토큰 | 추론 내역의 위치 | 피해야 할 계산 |
|---|---|---|---|
| OpenAI Responses | usage.output_tokens | usage.output_tokens_details.reasoning_tokens는 출력의 일부 | output_tokens + reasoning_tokens |
| OpenAI Chat Completions | usage.completion_tokens | usage.completion_tokens_details.reasoning_tokens는 출력의 일부 | completion_tokens + reasoning_tokens |
Gemini generateContent | usageMetadata.candidatesTokenCount + usageMetadata.thoughtsTokenCount | 두 출력 항목을 별도로 보고 | 후보 출력만 계산하거나 totalTokenCount에 사고 토큰을 다시 더하기 |
| Claude Messages | usage.output_tokens | 제공되는 경우 usage.output_tokens_details.thinking_tokens는 출력의 일부 | output_tokens + thinking_tokens |
OpenAI의 포함 관계는 출력 토큰 집계 문서, Gemini의 필드 관계는 UsageMetadata 참조, Claude의 세부 내역은 추론과 요금 문서에 나와 있습니다.
이 표를 모델 이름으로 분기하는 코드에 그대로 넣으면 안 됩니다. 예를 들어 Gemini 모델을 OpenAI 호환 주소로 호출했다면, 중간 서비스가 이미 추론을 포함한 completion_tokens로 변환했을 수 있습니다. 이 상태에서 추론을 다시 더하면 Gemini라도 과대 집계가 됩니다. 호출 주소, API 종류, SDK 또는 중간 서비스 버전, 원본 응답을 함께 보관하고 실제로 반환된 필드의 정의에 맞춰 계산해야 합니다. Gemini Interactions, Vertex AI, Live API에도 별도 확인 없이 generateContent 공식을 적용하지 마세요.
같은 출력 1,000토큰이 서로 다르게 기록되는 예
다음은 필드 관계를 보여 주기 위한 합성 데이터입니다. 실제 요청 결과나 공급자별 성능 비교가 아닙니다. 입력은 각각 500토큰, 과금할 출력은 1,000토큰, 그중 추론은 800토큰이라는 조건을 가정합니다.
| 응답 형식 | 원본 사용량의 주요 값 | 올바른 출력 합계 | 잘못 계산하면 |
|---|---|---|---|
| OpenAI Responses | input_tokens=500, output_tokens=1000, reasoning_tokens=800, total_tokens=1500 | 1,000 | 합계와 세부 내역을 더해 1,800 |
| Gemini generateContent | promptTokenCount=500, candidatesTokenCount=200, thoughtsTokenCount=800, totalTokenCount=1500 | 200 + 800 = 1,000 | 후보 출력만 사용해 200 |
| Claude Messages | input_tokens=500, output_tokens=1000, thinking_tokens=800 | 1,000 | 합계와 세부 내역을 더해 1,800 |
계산 방법을 비교하려고 출력 단가를 모두 100만 토큰당 10달러라는 가상 값으로 두면, 세 경우의 올바른 출력 비용은 각각 1,000 ÷ 1,000,000 × 10 = 0.01달러입니다. OpenAI와 Claude에 추론 800을 중복 합산하면 0.018달러로, 올바른 값보다 80% 높게 표시됩니다. Gemini에서 사고 토큰을 빠뜨리면 0.002달러로, 80% 낮게 표시됩니다. 실제 공급자 가격은 이 가상 단가와 무관합니다.
total_tokens나 totalTokenCount에 출력 단가를 곱하는 것도 잘못입니다. 위 예에서는 입력 500까지 출력 단가로 처리하게 됩니다. 특히 Gemini에서 totalTokenCount는 프롬프트, 사고, 후보 토큰을 합친 값이므로, 사고 토큰을 추가로 더할 이유가 없습니다.
출력에서 추론을 빼면 화면에 보이는 답변 토큰인가요?
정확히 그렇지는 않습니다. 출력에는 도구 호출이나 내부 형식에 필요한 토큰 등이 포함될 수 있습니다. 따라서 output_tokens - reasoning_tokens는 ‘추론으로 분류되지 않은 나머지 출력’으로 해석해야 하며, 화면에 표시한 문장을 다시 토큰화한 값과 같다고 단정하면 안 됩니다. OpenAI는 reasoning_tokens=0인 경우에도 이런 차이가 생길 수 있다고 공식 집계 문서에서 설명합니다.
한국어 글자 수나 답변 길이로 이 차이를 역산하면 검산이 더 어려워집니다. 공급자 사용량과 비교할 때는 원본 토큰 계수를 쓰고, 화면에 보이는 텍스트 길이는 별도 지표로 다루세요.
누락된 추론 내역과 출력 사용량 누락은 다릅니다
집계 코드의 값이 없으면 0 처리는 합계를 그럴듯하게 만들지만, 실제로는 비용 누락을 숨길 수 있습니다. 다음 세 상태를 분리하면 오류를 찾기 쉽습니다.
| 받은 응답 | 알 수 있는 것 | 저장할 상태 |
|---|---|---|
| OpenAI 또는 Claude의 출력 합계는 있고 추론 세부 내역만 없음 | 출력 비용의 기준은 알 수 있음. 추론 비중은 모름 | 출력 합계 유지, 추론 내역은 미확인 |
| Gemini의 후보 토큰은 있지만 사고 토큰 값이 없음 | 후보 토큰만 확인됨. 사고 토큰이 0인지 누락인지 확인 필요 | 확인 전까지 출력 비용 확정 보류 |
| 최종 사용량 자체를 받지 못함 | 응답 일부를 받았더라도 최종 계수는 모름 | 사용량 미확인 또는 확인 대기 |
Claude의 현재 문서에는 output_tokens_details.thinking_tokens가 설명되어 있습니다. 그렇다고 모든 모델, SDK 버전, 중간 서비스가 이 필드를 제공한다고 가정해서는 안 됩니다. 반대로 ‘Claude는 추론 토큰 수를 전혀 공개하지 않는다’는 설명도 현재 문서와 맞지 않습니다. 세부 내역이 없어도 output_tokens가 있다면 그 합계는 사용하되, 추론 비중만 미확인으로 남기면 됩니다. Claude 추론 비용 문서
음수, 정수가 아닌 값, 출력 합계보다 큰 추론 내역은 정상 데이터로 저장하지 않는 편이 좋습니다. 이런 값을 0으로 바꾸거나 합계에 맞춰 잘라 내면 수집기 오류를 놓칩니다. 원본을 보존하고 집계 오류로 분리하세요. 누락이 0을 의미한다고 해당 인터페이스가 명시한 경우에만 그 규칙을 적용해야 합니다.
실무에서는 원본 필드를 그대로 남긴 뒤, 한 번만 공통 형식으로 변환하는 방식이 유용합니다. 예를 들어 billed_output_tokens에는 출력 합계를, reasoning_tokens에는 그중 추론 내역을, usage_status에는 확정 여부를 저장할 수 있습니다. 이 이름들은 이 글에서 제안하는 내부 필드이며 공급자 표준이 아닙니다. 계산된 합계와 세부 내역을 다시 더하지 않도록 후속 집계의 기준도 하나로 정하세요.
스트리밍은 매번 오는 숫자를 더하면 안 됩니다
토큰 수가 스트리밍 이벤트에 실렸다는 이유만으로 증분값인 것은 아닙니다. Claude의 message_delta에서 사용량 계수는 누적값입니다. Claude 스트리밍 문서
가령 한 요청에서 출력 계수가 120 → 420 → 1,000으로 갱신되는 합성 사례를 생각해 보세요. 최종 출력 합계는 1,000이지, 세 이벤트를 더한 1,540이 아닙니다. 화면의 진행 상황은 최신 값으로 갱신하고, 최종 합계는 마지막 권위 있는 사용량 또는 SDK가 완성한 최종 메시지에서 가져와야 합니다. Claude의 추론 세부 내역은 최종 message_delta에 나타납니다.
연결이 420에서 끊겼다면 그 값이 최종 청구 토큰이라고 단정할 수도 없습니다. 마지막 관찰값과 최종 확정값을 구분해 보관하고, 공급자 사용량 기록과 나중에 대조해야 합니다. 이 누적 규칙을 다른 모든 스트리밍 API에 확장하지 말고, 각 인터페이스에서 누적값과 증분값을 확인하세요.
중복 로그는 제거하고, 별도 요청은 남기세요
‘같은 질문을 두 번 보냈다’와 ‘같은 사용량 기록이 두 번 저장됐다’는 다른 문제입니다. 전자는 실제 API 사용이 두 번 발생했을 수 있고, 후자는 내부 집계만 부풀릴 수 있습니다.
| 상황 | 처리 기준 |
|---|---|
| 같은 공급자 응답의 최종 사용량이 로그와 콜백에서 각각 수집됨 | 같은 응답 식별자로 확인되면 한 건으로 처리 |
| 같은 요청의 스트리밍 누적값과 최종 메시지가 함께 저장됨 | 최종 사용량으로 갱신. 둘을 별도 비용으로 합산하지 않음 |
| 시간 초과 뒤 재시도했으며 서로 다른 공급자 요청이 만들어짐 | 각 시도를 별도 보관하고 각각 사용량 확인 |
| 프롬프트는 같지만 요청 식별자가 다름 | 프롬프트 문자열만으로 중복 제거하지 않음 |
예를 들어 1,000 출력 토큰짜리 한 응답이 중복 수집됐다면 집계 결과는 1,000이어야 합니다. 하지만 재시도로 실제 요청이 두 번 실행되고 각 요청에서 1,000이 확인됐다면 출력 사용량은 2,000입니다. 앞의 가상 단가로는 각각 0.01달러와 0.02달러입니다. 요청이 실패했거나 클라이언트가 답변을 못 봤다는 사실만으로 공급자 처리량이 0이 되는 것은 아닙니다.
원본 사용량 외에 공급자·계정 또는 프로젝트, API 종류, 실제 모델, 공급자 요청 또는 응답 식별자, 내부 시도 식별자, 사용량 확정 시각을 함께 저장하면 이 구분이 가능합니다. 정확한 식별자 이름과 범위는 API마다 다르므로 임의의 문자열 하나를 모든 서비스에서 전역 고유 키로 가정하지 마세요.
이런 문제는 실제 집계 라이브러리에서도 발생한 적이 있습니다. browser-use의 과거 이슈 #4065는 completion_tokens에 추론 내역을 더해 표시 사용량과 비용을 부풀린 사례이며, 연결된 수정으로 종료되었습니다. 공급자가 실제로 중복 청구했다는 근거가 아니라, 로컬 집계에서 같은 부분합을 두 번 더할 수 있음을 보여 주는 사례입니다.
토큰 합계가 맞아도 청구 금액은 한 번 더 맞춰야 합니다
출력 사용량 검산이 끝나면 단가를 적용합니다. 입력과 출력만 있는 단순한 텍스트 요청이라면 기본 형태는 다음과 같습니다.
text요청 비용 = 입력 과금 토큰 × 해당 입력 단가 + 출력 과금 토큰 × 해당 출력 단가
가격표가 100만 토큰 기준이면 각각 1,000,000으로 나눠야 합니다. 실제 청구서를 맞출 때는 여기에 캐시 읽기·쓰기, 모델과 서비스 등급, 가격 적용일, 도구 호출 및 저장 비용 등 해당 항목을 반영해야 합니다. 캐시 토큰이 입력 합계에 이미 포함되는지 확인하지 않고 별도로 더하면, 추론 때와 같은 실수가 입력에서도 생깁니다.
특히 Google의 출력 가격은 사고 토큰을 포함하며, 가격표에는 Standard와 Batch가 구분되어 있습니다. ‘추론 토큰에는 Batch 출력 요금이 적용되지 않는다’는 일괄 규칙을 두면 안 됩니다. 실제 모델과 처리 방식의 Gemini 가격표를 적용하세요. 추론이라는 이유만으로 세 공급자 모두에 같은 배수를 곱하는 공식도 근거가 없습니다.
모델 선택과 총비용 비교가 다음 과제라면 Gemini·OpenAI·Claude API 비용 비교 가이드를 이어서 참고할 수 있습니다. 여기서 확정한 출력 토큰 수는 그 비교에 넣을 사용량이며, 그 자체로 청구서 전체를 재현한 결과는 아닙니다.
답변이 비어 있어도 추론 비용이 발생하나요?
발생할 수 있습니다. OpenAI의 추론 토큰은 출력 한도에 포함되므로, 추론 중 한도에 도달하면 표시할 답변 없이 불완전한 응답이 끝나고 비용이 발생할 수 있습니다. 응답 텍스트가 비었는지보다 usage와 완료 상태를 함께 확인해야 합니다. OpenAI 추론 가이드
Claude의 사고 요약만 짧게 보여 주면 요금도 줄어드나요?
표시되는 요약의 길이로 추론 사용량을 계산하지 않습니다. Claude는 숨겨진 사고에도 비용을 부과하며, 공식 문서는 요약 생성 자체에는 별도 비용이 없다고 설명합니다. 사용량 기준은 반환된 출력 합계입니다. Claude 추론과 비용
또한 모델에 따라 이전 사고 내용이 후속 요청의 문맥에 보존되면 입력으로 과금될 수 있습니다. 이것은 한 요청 안에서 추론 세부 내역을 출력 합계에 중복 합산하는 오류와 별개입니다. 대화가 길어질 때는 현재 출력과 다음 요청의 입력을 각각 추적해야 합니다. Claude thinking 문서
