Count tokens

응답을 생성하지 않고 Messages 요청의 입력 토큰 수를 셉니다. 게이트웨이는 요청을 Messages 요청과 같은 방식으로 변환한 뒤 모델 서버의 토크나이저에 질의합니다. 추론이 실행되지 않으므로 이 요청은 과금되지 않습니다.

POST/messages/count_tokens

URL

https://api.bricksum.com/v1/messages/count_tokens

요청

bash

curl https://api.bricksum.com/v1/messages/count_tokens \
  -H "x-api-key: $KILN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "system": "Answer briefly.",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

python

import os
from anthropic import Anthropic

# base_url is the API origin without /v1: the SDK appends /v1/messages/count_tokens.
client = Anthropic(
    base_url="https://api.bricksum.com",
    api_key=os.environ["KILN_API_KEY"],
)

count = client.messages.count_tokens(
    model="qwen3-32b",
    system="Answer briefly.",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(count.input_tokens)

typescript

import Anthropic from "@anthropic-ai/sdk";

// baseURL is the API origin without /v1: the SDK appends /v1/messages/count_tokens.
const client = new Anthropic({
  baseURL: "https://api.bricksum.com",
  apiKey: process.env.KILN_API_KEY,
});

const count = await client.messages.countTokens({
  model: "qwen3-32b",
  system: "Answer briefly.",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(count.input_tokens);

응답

200 OK

{
  "input_tokens": 21
}

404 Not Found

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "token counting is not available for this model"
  }
}

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

인증

게이트웨이가 처리하는 엔드포인트의 인증 방식은 모두 같으며, API 레퍼런스 페이지에서 설명합니다.

요청 본문

지원 상태

지원: 게이트웨이가 처리하거나, 공개된 실측에서 동작이 확인된 항목입니다.
전달만 함: 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
무시됨: 200으로 수락되지만 적용되지 않습니다. 응답의 나머지는 정상입니다.
미지원: 에러로 거부되거나, 설명에 적힌 모델에서 동작하지 않습니다.

공통 파라미터

아래 파라미터의 정의는 API 레퍼런스 페이지에 한 번만 정리했습니다. 여기에는 이 엔드포인트에서 다른 점만 적었습니다.

modelstring지원
여기서는 선택 사항입니다. 이 필드가 비어 있거나 없으면 게이트웨이에 설정된 기본 모델을 사용합니다. 404는 not_found_error이며, 토크나이저가 토큰 수를 셀 수 없을 때도 같은 상태로 응답합니다.
전체 정의 보기
messagesarray필수지원
Messages 엔드포인트와 같은 형식이며 같은 규칙으로 변환되므로, thinking과 document처럼 제거되는 블록은 세지 않습니다. 배열이 비어 있거나 없으면 400(invalid_request_error)으로 거부됩니다.
전체 정의 보기
toolsarray무시됨
수락되지만 토크나이저로 보내지 않습니다. 토큰 수에 툴 정의는 포함되지 않습니다.
전체 정의 보기
tool_choiceobject무시됨
수락되지만 토크나이저로 보내지 않습니다. thinking, output_config, max_tokens, 샘플링 파라미터도 마찬가지입니다.
전체 정의 보기

이 엔드포인트에만 있는 파라미터

systemstring | array지원
시스템 프롬프트입니다. 문자열 또는 text 블록 배열로 보냅니다. 대화 맨 앞의 system 메시지로 계산됩니다.

토크나이저에는 model과 변환된 messages만 전달됩니다. 그 밖의 필드는 제거되며 에러가 발생하지는 않습니다.

응답 본문

필드	타입	설명
input_tokens	integer	변환된 messages의 토큰 수입니다. 모델 서버의 토크나이저가 chat 템플릿을 적용해 센 값입니다. 응답의 유일한 필드입니다.

에러

인증을 통과한 뒤의 에러는 Anthropic 형식({"type": "error", "error": {"type", "message"}})으로 반환됩니다. 메시지 문구가 아니라 HTTP 상태와 error.type으로 분기하세요. error.type 칸이 비어 있는 행은 요청이 이 엔드포인트에 도달하기 전에 게이트웨이가 반환하는 에러이며, 표 아래에 있는 본문 형식을 사용합니다.

전체 상태 코드는 에러 페이지에 있습니다.

상태 · error.type	원인	조치
400invalid_request_error	본문이 올바른 JSON이 아니거나, messages가 비어 있거나 없거나, 메시지의 content가 문자열도 블록 배열도 아닙니다.	요청 본문을 수정하세요. 그대로 재시도하지 마세요.
404not_found_error	모델 ID가 카탈로그에 없습니다.	GET /models로 ID를 확인하세요.
404not_found_error	이 모델에서는 토큰 수 계산을 사용할 수 없습니다. 모델 백엔드를 선택하지 못했거나, 토크나이저에 연결할 수 없거나 토크나이저가 요청을 거부했거나, 응답에 토큰 수가 없는 경우입니다. 이 엔드포인트는 이런 실패를 5xx가 아닌 404로 응답합니다.	클라이언트에서 토큰 수를 추정하세요. Claude Code는 자체적으로 추정값을 사용합니다.
405invalid_request_error	메서드가 POST가 아닙니다.	POST로 요청하세요.

401, 402, 403, 429는 요청이 이 엔드포인트에 도달하기 전에 게이트웨이가 반환합니다. 이 에러들은 API 레퍼런스 페이지에 한 번만 정리했습니다.

인증, 크레딧, 예산, 레이트 리밋(분당 요청 수, 분당 토큰 수) 에러는 Anthropic 형식으로 변환되기 전에 게이트웨이가 반환합니다. 본문은 Anthropic 형식이 아닙니다.

json

{
  "error": {
    "message": "invalid API key",
    "type": "authorization"
  }
}

제한

과금: 과금되지 않습니다. 게이트웨이는 이 엔드포인트에 대해 usage 이벤트를 발행하지 않으며, 응답에 X-Neocloud-Generation-Id 헤더가 없습니다.
Claude Code에서는 선택 사항입니다. 이 엔드포인트가 404로 응답하면 Claude Code는 자체 추정값을 사용하고 /context에는 근사치가 표시됩니다.

컨텍스트 길이, 요청 본문 크기, 타임아웃, 조직별 레이트 리밋도 여기에 그대로 적용되며, API 레퍼런스 페이지에 한 번만 정리했습니다.

429의 헤더와 재시도 방법은 레이트 리밋 페이지에 있습니다.