# 사용량과 과금

> usage 객체와 usage.cost, 비용 계산 방식, generation ID 헤더, 키 확인, 과금 대상을 설명합니다.

Source: https://kiln.bricksum.com/docs/ko/usage-billing

요금은 미리 충전한 USD 크레딧에서 차감됩니다. 모든 응답에는 그 요청의 비용이 담겨 있습니다. usage 객체에 토큰 수가 담기고, 게이트웨이가 여기에 USD 비용을 추가합니다. 이 페이지는 usage 객체, 비용 계산 방식, 요청 ID 헤더, 과금되는 요청과 과금되지 않는 요청을 설명합니다.

## usage 객체

비스트리밍 응답은 본문에 OpenAI 형식의 usage를 담습니다. 기본 필드는 prompt_tokens, completion_tokens, total_tokens입니다. 모델 서버가 프롬프트 일부를 prefix 캐시에서 제공하면 prompt_tokens_details.cached_tokens가 함께 오며, 이 토큰은 더 낮은 캐시 입력 단가로 과금됩니다. 모델이 reasoning을 보고하면 completion_tokens_details.reasoning_tokens가 함께 옵니다. 이 값은 completion_tokens에 포함되어 있고 출력으로 과금됩니다. 여기에 cost 필드가 하나 더 있습니다. 이 요청으로 크레딧에서 차감된 USD 금액이며, 모델이 아니라 게이트웨이가 추가합니다.

스트림에서는 stream_options.include_usage를 설정하면 같은 객체가 마지막 청크에 담겨 옵니다. 자세한 내용은 [스트리밍](https://kiln.bricksum.com/docs/ko/streaming) 페이지를 참고하세요.

**200 OK**
```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "qwen3-32b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "cost": 0.000001155
  }
}
```

이 예시의 토큰 수와 cost는 gpt-oss-120b에서 측정한 예시 값이며, qwen3-32b의 값이 아닙니다.

## 비용 계산 방식

비용은 요청 시점의 모델 토큰 단가로 계산한 세 항의 합입니다. 캐시된 프롬프트 토큰은 prompt_tokens의 일부이며, 입력 단가 대신 캐시 입력 단가를 적용합니다.

**USD**
```text
cost = (prompt_tokens - cached_tokens) x input price
     + cached_tokens                  x cached-input price
     + completion_tokens              x output price
```

모든 모델의 100만 토큰당 단가는 [모델 카탈로그](https://kiln.bricksum.com/models)에 있습니다. 카탈로그 API는 단가를 price_input_per_m, price_cached_input_per_m, price_output_per_m 필드로 반환합니다. 단가는 USD 기준이며 VAT는 포함되지 않습니다.

## 요청 ID 헤더

계측된 모든 응답에는 `X-Neocloud-Generation-Id` 헤더가 실립니다. 값은 그 요청의 사용량 이벤트 ID입니다. 요청 로그와 함께 저장하고, 차감 내역이나 에러를 문의할 때 이 값을 함께 보내세요.

## 키 확인

키 자체로 인증하는 GET /v1/key는 그 키의 프로젝트, 상태, 지출 한도, 만료, 지금까지의 사용액을 반환합니다. 콘솔에 접근할 수 없는 팀원도 자기 키를 확인할 수 있습니다. 평문 키는 반환하지 않습니다. 무효·정지·만료 키는 모두 401을 받습니다.

**curl**
```bash
curl https://api.bricksum.com/v1/key \
  -H "Authorization: Bearer sk-bk-..."
```

**200 OK**
```json
{
  "id": "key_...",
  "org_id": "org_...",
  "project_id": "proj_...",
  "name": "prod-backend",
  "prefix": "sk-bk-",
  "last4": "a1b2",
  "status": "active",
  "spend_limit_usd": 50,
  "expires_at": null,
  "usage_usd": 12.34,
  "last_used_at": "2026-09-11T07:00:00Z",
  "created_at": "2026-08-01T00:00:00Z"
}
```

## 과금 대상

- 모델 서버에 도달한 요청마다 사용량 이벤트가 1건 기록되며, 서버가 보고한 usage 토큰 수를 기준으로 과금합니다.
- 모델에 도달하기 전에 게이트웨이가 거부한 요청은 과금되지 않습니다. 상태 코드와 원인은 [에러](https://kiln.bricksum.com/docs/ko/errors) 페이지에 정리되어 있습니다.
- 모델 서버가 에러를 반환하거나 스트림 도중 실패하면 이벤트는 0 토큰으로 기록되고 아무것도 과금되지 않습니다.
- 클라이언트가 스트림 도중 연결을 끊으면 게이트웨이는 사용량을 기록하기 위해 스트림을 끝까지 읽으며, 생성된 토큰은 과금됩니다.

## 요청이 거부되는 경우

조직의 크레딧 잔액이 0 이하이거나, 조직이 월 예산에 도달했거나, 키가 지출 한도에 도달하면 게이트웨이는 모델을 호출하기 전에 요청을 `402 Payment Required` 상태로 거부하며, 이렇게 거부된 요청은 과금되지 않습니다. 잔액·원장·만료는 [크레딧 페이지](https://kiln.bricksum.com/app/credits)에서 확인하세요. 예산, 키 한도, 크레딧 만료는 조직과 예산 페이지에서 설명합니다.