사용량과 과금

요금은 미리 충전한 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를 설정하면 같은 객체가 마지막 청크에 담겨 옵니다. 자세한 내용은 스트리밍 페이지를 참고하세요.

200 OK

{
  "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

cost = (prompt_tokens - cached_tokens) x input price
     + cached_tokens                  x cached-input price
     + completion_tokens              x output price

모든 모델의 100만 토큰당 단가는 모델 카탈로그에 있습니다. 카탈로그 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

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

200 OK

{
  "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 토큰 수를 기준으로 과금합니다.
모델에 도달하기 전에 게이트웨이가 거부한 요청은 과금되지 않습니다. 상태 코드와 원인은 에러 페이지에 정리되어 있습니다.
모델 서버가 에러를 반환하거나 스트림 도중 실패하면 이벤트는 0 토큰으로 기록되고 아무것도 과금되지 않습니다.
클라이언트가 스트림 도중 연결을 끊으면 게이트웨이는 사용량을 기록하기 위해 스트림을 끝까지 읽으며, 생성된 토큰은 과금됩니다.

요청이 거부되는 경우

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