guides/token-counting.md +5 −5
6 6
7- **Optimize prompts** to fit within context limits7- **Optimize prompts** to fit within context limits
8- **Estimate costs** before making API calls8- **Estimate costs** before making API calls
99- **Route requests** based on size (e.g., smaller prompts to faster models)- **Route requests** based on size (for example, smaller prompts to faster models)
10- **Avoid surprises** with images and files—no more character-based estimation10- **Avoid surprises** with images and files—no more character-based estimation
11 11
1212The [input token count endpoint](https://developers.openai.com/api/reference/python/resources/responses/subresources/input_tokens/methods/count) accepts the same input format as the [Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create). Pass text, messages, images, files, tools, or conversations—the API returns the exact count the model will receive.The [input token count endpoint](https://developers.openai.com/api/reference/resources/responses/subresources/input_tokens/methods/count) accepts the same input format as the [Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create). Pass text, messages, images, files, tools, or conversations—the API returns the exact count the model will receive.
13 13
14The count includes formatting tokens used to represent request structure, such as message roles and boundaries. These tokens might not appear in the text or fields you tokenize locally.14The count includes formatting tokens used to represent request structure, such as message roles and boundaries. These tokens might not appear in the text or fields you tokenize locally.
15 15
19 19
20- **Images and files** are not supported—estimates like `characters / 4` are inaccurate20- **Images and files** are not supported—estimates like `characters / 4` are inaccurate
21- **Tools and schemas** add tokens that are hard to count locally21- **Tools and schemas** add tokens that are hard to count locally
2222- **Model-specific behavior** can change tokenization (e.g., reasoning, caching)- **Model-specific behavior** can change tokenization (for example, reasoning, caching)
23 23
24The token counting API handles all of these. Use the same payload you would send to `responses.create` and get an accurate count. Then plug the result into your message validation or cost estimation flow.24The token counting API handles all of these. Use the same payload you would send to `responses.create` and get an accurate count. Then plug the result into your message validation or cost estimation flow.
25 25
781 781
782## Count tokens with files782## Count tokens with files
783 783
784784[File inputs](https://developers.openai.com/api/docs/guides/file-inputs)—currently PDFs—are supported. Pass `file_id`, `file_url`, or `file_data` as you would for `responses.create`. The token count reflects the model’s full processed input.[File inputs](https://developers.openai.com/api/docs/guides/file-inputs) (currently PDFs) are supported. Pass `file_id`, `file_url`, or `file_data` as you would for `responses.create`. The token count reflects the model’s full processed input.
785 785
786## Understand output token counts786## Understand output token counts
787 787
793 793
794## API reference794## API reference
795 795
796796For full parameters and response shape, see the [Count input tokens API reference](https://developers.openai.com/api/reference/python/resources/responses/subresources/input_tokens/methods/count). The endpoint is:For full parameters and response shape, see the [Count input tokens API reference](https://developers.openai.com/api/reference/resources/responses/subresources/input_tokens/methods/count). The endpoint is:
797 797
798```798```
799POST /v1/responses/input_tokens799POST /v1/responses/input_tokens