> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# टोकन उपयोग

प्रत्येक LLM प्रतिक्रिया में एक `usage` ऑब्जेक्ट होता है जो बताता है कि अनुरोध ने कितने टोकन खपत किए। Sunra उपयोग की रिपोर्ट उसी endpoint की शब्दार्थ (semantics) में करता है जिसे आपने कॉल किया था: एक Messages प्रतिक्रिया Anthropic अनुबंध का पालन करती है, और एक Chat Completions या Responses प्रतिक्रिया OpenAI अनुबंध का पालन करती है।

ये आकार जानबूझकर भिन्न हैं। Chat Completions प्रतिक्रिया पढ़ने वाला एक OpenAI SDK OpenAI शब्दार्थ मानता है, और Messages प्रतिक्रिया पढ़ने वाला एक Anthropic SDK Anthropic शब्दार्थ मानता है। प्रत्येक endpoint एक साझा आकार में बलपूर्वक ढाले जाने के बजाय वही निभाता है जिसका वादा उसका अपना विनिर्देश करता है।

| Endpoint               | प्रॉम्प्ट गणना फ़ील्ड | क्या कैश्ड टोकन इसमें शामिल हैं?                                              |
| ---------------------- | --------------------- | ----------------------------------------------------------------------------- |
| `/v1/messages`         | `input_tokens`        | नहीं — तीनों इनपुट बकेट परस्पर अनन्य हैं                                      |
| `/v1/chat/completions` | `prompt_tokens`       | हाँ — कैश्ड टोकन एक उपसमुच्चय हैं, जिनका विवरण `prompt_tokens_details` में है |
| `/v1/responses`        | `input_tokens`        | हाँ — कैश्ड टोकन एक उपसमुच्चय हैं, जिनका विवरण `input_tokens_details` में है  |

<Warning>
  `/v1/messages` और `/v1/responses` दोनों `input_tokens` फ़ील्ड नाम का उपयोग करते हैं, और इसका दोनों जगह एक ही अर्थ नहीं है। Messages पर यह केवल ताज़ा इनपुट है। Responses पर यह पूरा प्रॉम्प्ट है, कैश्ड टोकन सहित।
</Warning>

## Messages

`/v1/messages` पर, तीनों इनपुट बकेट **परस्पर अनन्य** हैं। कोई भी टोकन दो बार नहीं गिना जाता, इसलिए प्रॉम्प्ट का कुल योग उनका जोड़ है:

```
total prompt = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
```

<ResponseField name="input_tokens" type="integer">
  केवल ताज़ा इनपुट टोकन। दोनों कैश बकेट में से किसी को भी शामिल नहीं करता।
</ResponseField>

<ResponseField name="cache_creation_input_tokens" type="integer">
  इस अनुरोध द्वारा कैश में लिखे गए टोकन।
</ResponseField>

<ResponseField name="cache_read_input_tokens" type="integer">
  कैश से इस अनुरोध को परोसे गए टोकन।
</ResponseField>

<ResponseField name="output_tokens" type="integer">
  मॉडल द्वारा उत्पन्न टोकन।
</ResponseField>

<ResponseField name="total_tokens" type="integer">
  तीनों इनपुट बकेट और `output_tokens` का जोड़। गैर-streaming प्रतिक्रियाओं पर मौजूद।
</ResponseField>

अनुपस्थित या `null` बकेट को शून्य गिना जाता है।

### व्यावहारिक उदाहरण

वही 19,000-टोकन उपसर्ग `claude-opus-4-8` के विरुद्ध दो बार भेजा गया। पहला अनुरोध कैश लिखता है; दूसरा उसे पढ़ता है।

```json ठंडा अनुरोध (कैश राइट) theme={null}
{
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 19349,
    "cache_read_input_tokens": 0,
    "output_tokens": 2,
    "total_tokens": 19359,
    "sunra_usage_semantics": "anthropic.exclusive.v1"
  }
}
```

```json गर्म अनुरोध (कैश रीड) theme={null}
{
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 19349,
    "output_tokens": 2,
    "total_tokens": 19359,
    "sunra_usage_semantics": "anthropic.exclusive.v1"
  }
}
```

`input_tokens` दोनों अनुरोधों में 8 पर बना रहता है, क्योंकि 8 ही हर बार वास्तव में नया इनपुट है। 19,349-टोकन उपसर्ग creation बकेट से read बकेट में चला जाता है। दोनों अनुरोधों का योग समान 19,359 कुल टोकन है, लेकिन उनकी लागत समान नहीं है: कैश राइट और कैश रीड की अपनी-अपनी प्रति-टोकन दरें हैं, यही कारण है कि उन्हें अलग बकेट के रूप में रिपोर्ट किया जाता है।

## Chat Completions और Responses

ये endpoint OpenAI शब्दार्थ को अपरिवर्तित रिपोर्ट करते हैं। प्रॉम्प्ट गणना **पूरा** प्रॉम्प्ट है, और कैश्ड टोकन उसका एक **उपसमुच्चय** हैं जिन्हें अलग से रिपोर्ट किया जाता है।

```json /v1/chat/completions theme={null}
{
  "usage": {
    "prompt_tokens": 19357,
    "completion_tokens": 2,
    "total_tokens": 19359,
    "prompt_tokens_details": {
      "cached_tokens": 19349
    }
  }
}
```

`prompt_tokens` और `cached_tokens` को जोड़ने पर दोहरी गणना होती है। इन endpoint पर ताज़ा इनपुट पाने के लिए, घटाएँ:

```
fresh input = prompt_tokens - prompt_tokens_details.cached_tokens
```

यही नियम `/v1/responses` पर `input_tokens` और `input_tokens_details.cached_tokens` के साथ लागू होता है।

## `sunra_usage_semantics` मार्कर

जिन प्रतिक्रियाओं को Sunra ने सामान्यीकृत किया है, वे `usage` के भीतर एक मार्कर रखती हैं:

```json theme={null}
"sunra_usage_semantics": "anthropic.exclusive.v1"
```

यह मार्कर **प्रतिक्रिया** के बारे में एक वादा है, किसी एकल घटना या फ़ील्ड के बारे में नहीं। बिना streaming वाली प्रतिक्रिया में यह मूल `usage` ऑब्जेक्ट में प्रकट होता है; streaming वाली प्रतिक्रिया में यह `message_start` में प्रकट होता है, यानी उस घटना में जो इनपुट बकेट लाती है। जब यह इस मान के साथ मौजूद होता है, तो इस पृष्ठ की गारंटियाँ लागू होती हैं: तीनों इनपुट बकेट परस्पर अनन्य हैं, और `total_tokens` — जहाँ मौजूद हो — उनका जोड़ और `output_tokens` है।

**इसकी अनुपस्थिति भी एक वादा है।** Sunra केवल उन्हीं प्रतिक्रिया आकारों को सामान्यीकृत करता है जिन्हें उसने मापा है। बाकी सब कुछ अपस्ट्रीम प्रदाता से बिना छेड़छाड़ के अग्रेषित किया जाता है और बिना मार्कर के छोड़ दिया जाता है, और जिस प्रतिक्रिया पर मार्कर नहीं है, उसके बकेट की ज़मानत Sunra नहीं लेता।

यह अनुमान लगाने के लिए कि कोई प्रतिक्रिया किस परिपाटी का पालन करती है, संख्याओं का निरीक्षण करने के बजाय मार्कर पर assert करें। आकार सूँघना (shape sniffing) वही है जिसे प्रतिस्थापित करने के लिए यह फ़ील्ड मौजूद है — "बकेट अवश्य अनन्य होंगे क्योंकि उनका जोड़ प्रॉम्प्ट गणना से अधिक है" जैसी युक्ति एक से अधिक परिपाटी से संतुष्ट हो जाती है और अंततः किसी प्रतिक्रिया को ग़लत पढ़ेगी।

```python theme={null}
usage = response["usage"]

if usage.get("sunra_usage_semantics") == "anthropic.exclusive.v1":
    total_prompt = (
        usage["input_tokens"]
        + usage.get("cache_creation_input_tokens", 0)
        + usage.get("cache_read_input_tokens", 0)
    )
else:
    # Not normalized by Sunra. Treat the upstream shape as unverified
    # and consult that provider's own documentation.
    total_prompt = None
```

केवल `/v1/messages` की प्रतिक्रियाएँ ही कभी यह मार्कर रखती हैं। Chat Completions और Responses OpenAI विनिर्देश का पालन करते हैं और उन पर मार्कर नहीं लगाया जाता।

यह मान संस्करणबद्ध है। इन फ़ील्ड के अर्थ में कोई breaking change एक नए मान के अंतर्गत जारी होगा, इसलिए `anthropic.exclusive.v1` के विरुद्ध समानता जाँच चुपचाप किसी दूसरे अनुबंध को पढ़ना शुरू नहीं करेगी।

## Streaming

streaming वाले Messages अनुरोध पर, उपयोग दो घटनाओं में आता है। `message_start` इनपुट पक्ष और मार्कर लाता है। अंतिम `message_delta` केवल `output_tokens` लाता है। `message_start` में मार्कर पर assert करें, फिर दोनों घटनाओं को सामान्य ढंग से मिलाएँ — बाद वाली घटना के usage को पहले वाले के ऊपर लागू करना — ताकि ऊपर प्रलेखित मान प्राप्त हों।

streaming प्रतिक्रियाओं से `total_tokens` छोड़ दिया जाता है। कोई एकल घटना इनपुट और आउटपुट दोनों पक्षों को नहीं जानती, इसलिए stream के बीच में गणना किया गया कोई भी योग ग़लत होगा। stream पूरा होने के बाद बकेट का जोड़ स्वयं करें।

## पिछले व्यवहार से माइग्रेट करना

Sunra पहले `/v1/messages` पर अपस्ट्रीम `usage` ऑब्जेक्ट को हूबहू अग्रेषित करता था। कुछ प्रदाताओं के आगे की अनुवाद परत cache-creation टोकन को `input_tokens` **के भीतर** मोड़ देती है, इसलिए जो कॉलर Anthropic अनुबंध का पालन करके तीनों बकेट जोड़ता था, वह cache-creation टोकन को दो बार गिनता था।

* **यदि आप तीनों बकेट जोड़ते हैं**, जैसा कि Anthropic अनुबंध वर्णन करता है, तो आप अब सही हैं। आपकी ओर से किसी बदलाव की आवश्यकता नहीं है।
* **यदि आपने पुराने व्यवहार की भरपाई की थी** — स्वयं `input_tokens` में से `cache_creation_input_tokens` घटाकर, या अन्यथा उस मोड़ को रिवर्स-इंजीनियर करके — तो **रोक दें**। वह सुधार अब उन टोकन को घटाएगा जो पहले ही बाहर रखे जा चुके हैं और आपके इनपुट को कम आँकेगा।
* **यदि आप `total_tokens` पढ़ते हैं**, तो यह पूरी गणना रिपोर्ट करना जारी रखता है: ताज़ा इनपुट, दोनों कैश बकेट, और आउटपुट।

इस बदलाव को किसी deploy तिथि के बजाय मार्कर पर आधारित करें, ताकि वही कोड पथ मार्कर वाली और बिना मार्कर वाली दोनों प्रतिक्रियाओं के विरुद्ध सही रहे।