For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

토큰 수 계산

요청을 보내기 전에 정확한 입력 토큰 수를 확인하세요.

모델에 요청을 보내기 전에 해당 요청에 필요한 입력 토큰 수를 확인할 수 있습니다. 토큰 수를 미리 계산하면 다음과 같은 작업을 할 수 있습니다.

  • 컨텍스트 한도에 맞게 프롬프트 최적화하기
  • API를 호출하기 전에 비용 추정하기
  • 짧은 프롬프트를 더 빠른 모델로 보내는 등 요청 크기에 따라 요청 라우팅하기
  • 문자 수로 추정할 필요 없이 이미지와 파일의 토큰 수를 정확히 파악하기

입력 토큰 수 계산 엔드포인트는 Responses API와 같은 입력 형식을 사용합니다. 텍스트, 메시지, 이미지, 파일, 도구 또는 대화를 전달하면 API가 모델에 전달될 정확한 토큰 수를 반환합니다.

이 수에는 메시지의 역할이나 경계 등 요청 구조를 나타내는 형식 지정 토큰도 포함됩니다. 로컬에서 토큰화하는 텍스트나 필드에는 이러한 토큰이 나타나지 않을 수 있습니다.

토큰 수 계산 API를 사용하는 이유

tiktoken과 같은 로컬 토크나이저는 일반 텍스트를 처리할 수 있지만 다음과 같은 한계가 있습니다.

  • 이미지와 파일은 지원하지 않습니다. characters / 4와 같은 방식으로 추정한 값은 부정확합니다.
  • 도구와 스키마를 사용하면 로컬에서 계산하기 어려운 토큰이 추가됩니다.
  • 추론이나 캐싱 등 모델별 동작에 따라 토큰화 방식이 달라질 수 있습니다.

토큰 수 계산 API는 이러한 경우를 모두 처리합니다. responses.create에 보낼 때와 같은 페이로드를 전달하면 정확한 토큰 수를 얻을 수 있습니다. 이 값을 메시지 검증이나 비용 추정 플로우에 활용하세요.

기본 메시지의 토큰 수 계산

간단한 텍스트 입력
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra", input="Tell me a joke."
)
print(response.input_tokens)

대화의 토큰 수 계산

여러 턴으로 구성된 대화
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    input=[
        {"role": "user", "content": "What is 2 + 2?"},
        {"role": "assistant", "content": "2 + 2 equals 4."},
        {"role": "user", "content": "What about 3 + 3?"},
    ],
)
print(response.input_tokens)

지침이 포함된 입력의 토큰 수 계산

시스템 지침이 포함된 입력
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    instructions="You are a helpful assistant that explains concepts simply.",
    input="Explain quantum computing in one sentence.",
)
print(response.input_tokens)

이미지가 포함된 입력의 토큰 수 계산

이미지에 필요한 토큰 수는 이미지 크기와 세부 수준에 따라 달라집니다. 토큰 수 계산 API가 정확한 값을 반환하므로 직접 추정할 필요가 없습니다.

이미지가 포함된 입력
from openai import OpenAI

client = OpenAI()

# Use file_id from uploaded file, or image_url for a URL
response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_image",
                    "image_url": "https://example.com/chart.png",
                },
                {"type": "input_text", "text": "Summarize this chart."},
            ],
        }
    ],
)
print(response.input_tokens)

file_id(Files API에서 받은 ID) 또는 image_url(URL 또는 base64 데이터 URL)을 사용할 수 있습니다. 자세한 내용은 이미지 및 비전 가이드를 참고하세요.

도구가 포함된 입력의 토큰 수 계산

함수 스키마, MCP 서버 등의 도구 정의도 컨텍스트에서 토큰을 차지합니다. 다음과 같이 입력과 도구 정의를 함께 전달해 토큰 수를 계산하세요.

함수 도구가 포함된 입력
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get the current weather in a location",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        }
    ],
    input="What is the weather in San Francisco?",
)
print(response.input_tokens)

파일이 포함된 입력의 토큰 수 계산

파일 입력을 지원합니다. 현재 지원하는 형식은 PDF입니다. file_id, file_url 또는 file_data를 responses.create를 호출할 때와 같은 방식으로 전달하세요. 반환되는 토큰 수에는 모델이 처리하는 전체 입력이 반영됩니다.

출력 토큰 수 이해하기

출력 토큰 사용량에는 응답에 표시되는 텍스트의 토큰을 비롯해 모델이 생성한 모든 토큰이 포함됩니다. Responses API는 이 총합을 output_tokens로, Chat Completions API는 completion_tokens로 보고합니다.

GPT-5 모델을 비롯한 일부 모델은 응답 채널, 도구 호출 및 기타 메시지 구조 요소의 형식을 지정하거나 경계를 표시하는 토큰을 생성합니다. 이러한 형식 지정 토큰은 메시지 본문이나 logprobs에 나타나지 않으며, 사용량 내역에서도 별도 항목으로 표시되지 않을 수 있습니다. 따라서 보고된 출력 토큰 수나 완성 토큰 수는 화면에 표시되는 토큰 수 또는 logprobs에 포함된 토큰 수보다 많을 수 있습니다. 보고된 reasoning_tokens 값이 0인 경우에도 마찬가지입니다.

max_output_tokens와 max_completion_tokens는 화면에 표시되지 않는 토큰을 포함해 모델이 생성하는 모든 토큰의 총수를 제한합니다. 표시되지 않는 토큰 수는 모델과 응답 구조에 따라 달라지므로 보고된 사용량과 화면에 표시되는 출력 토큰 수의 차이가 일정하다고 가정하지 마세요. 화면에 표시할 출력이 일정 분량 이상 필요하다면 토큰 한도를 여유 있게 설정하세요.

API 레퍼런스

전체 매개변수와 응답 구조는 입력 토큰 수 계산 API 레퍼런스를 참고하세요. 엔드포인트는 다음과 같습니다.

POST /v1/responses/input_tokens

응답에는 input_tokens(정수)와 object: "response.input_tokens"가 포함됩니다.