Token Types
A request usually consists of input, cache read, cache write, output, and other billing dimensions. Common usage fields are defined as follows:Whether reasoning tokens are returned in the API response depends on the model, protocol, and request parameters. Some models return
reasoning or reasoning_content; others do not. Even when reasoning tokens are not returned as visible content, they are still included in platform usage statistics.Billing Formula
For token-based model requests, the complete billing formula is: Cost = input tokens x input unit price + cache read tokens x cache read unit price + cache write tokens x cache write unit price + output tokens x output unit price- In this formula, input tokens refer to input tokens that are not served from cache. Input, cache read, cache write, and output can have separate unit prices. Check the model detail page in Models for the exact prices.
- Image input is converted into input tokens and billed at the input unit price.
- Speech models are billed by audio duration. For ASR, usage is based on input audio duration. For TTS, usage is based on output audio duration. Check the model detail page in Models for the exact unit price.
max_completion_tokens
max_completion_tokens limits the total generation budget, which means the sum of reasoning tokens and visible output tokens. It does not only limit the final visible answer.
When you use a reasoning model, internal reasoning may consume part of the generation budget first. If max_completion_tokens is too small, you may see the following results:
- The visible answer is short, but output tokens are high.
- The reasoning process exhausts the generation budget, so
contentis empty. - The answer is truncated and
finish_reasonislength.
max_completion_tokens or adjusting thinking_budget. thinking_budget is a hint, not a strict limit. A model may use it to control reasoning length, partially apply it, or ignore it.
We recommend using
max_completion_tokens. If you see max_tokens in a third-party tool or older example, it has the same general meaning.View Usage
You can view per-request token usage on the Usage Detail page. Usage Detail shows fields such as Input, Image Input, Cache Read, Cache Write, Reasoning, Output, and Total Tokens. Reasoning is already included in Output, so do not add Reasoning and Output together when analyzing cost. For details, see View Usage.Which Requests Are Billed
Requests that complete normally and generate model usage are billed based on actual usage. Requests rejected before reaching the model are not billed, such as invalid parameters, authentication failures, insufficient balance, missing permission, model not found, or rate limit errors. Platform-side failures are not billed. For error response structures and handling guidance, see Error Handling.Cost Control Tips
- Control input length: Remove irrelevant history, long documents, and repeated context to avoid continuous input token growth.
- Control generation budget: Set
max_completion_tokensreasonably to avoid unnecessarily long output. - Control reasoning budget: For reasoning models, set
thinking_budgetbased on reasoning depth, latency, and cost requirements. - Choose the right model: Use free or lower-cost models during development, then choose the production model based on quality and cost.
- Reuse long context: For repeated long prefixes, fixed system prompts, or long multi-turn materials, see Prompt Caching.
- Keep prompt prefixes stable: Keep system messages, tool definitions, and few-shot examples consistent in order and content across requests to improve Prompt Caching hit opportunities.
- Reduce irrelevant context: For large knowledge bases, use Embedding to build RAG and pass only relevant chunks to the generation model.
- Separate API keys by application: Create separate API keys for different applications, and configure monthly budget, total budget, TPM, and RPM. For details, see API Keys.
FAQ
Why is the visible answer short but billed token usage high?
Why is the visible answer short but billed token usage high?
For reasoning models, internal reasoning consumes reasoning tokens. Reasoning tokens may not be returned as visible content, but they are included in output tokens and billed at the output unit price. A short visible answer does not necessarily mean output tokens are low.
Why is content empty after I set a small max_completion_tokens value?
Why is content empty after I set a small max_completion_tokens value?
max_completion_tokens limits the sum of reasoning tokens and visible output tokens. If the reasoning process exhausts the generation budget, the model may have no remaining budget to generate the final visible answer, so content may be empty.Why is the answer truncated with finish_reason set to length?
Why is the answer truncated with finish_reason set to length?
This usually means generation reached the
max_completion_tokens limit, or the request exceeded the model’s context limit. You can reduce input length, increase max_completion_tokens, or enable streaming to improve long-response handling.Why can Usage Detail show reasoning tokens when the API response does not return them?
Why can Usage Detail show reasoning tokens when the API response does not return them?
Whether the API returns
reasoning or reasoning_content depends on the model, protocol, and request parameters. Even if the reasoning content is not returned in the response, the platform still counts the model’s internal reasoning usage and displays it in Usage Detail.Can thinking_budget strictly limit reasoning tokens?
Can thinking_budget strictly limit reasoning tokens?
No.
thinking_budget is a hint, not a strict limit. It can help the model control reasoning length, but support and adoption vary by model.In multi-turn conversations, is the conversation history billed every turn?
In multi-turn conversations, is the conversation history billed every turn?
Yes. Each request is independent, so the full conversation history you send is counted as input for that request. Prompt Caching can reduce the processing cost of repeated prefixes, but it does not make the model automatically inherit previous context.

