टोकन उपयोग

प्रत्येक 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` में है

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

Messages

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

total prompt = input_tokens + cache_creation_input_tokens + cache_read_input_tokens

integer

केवल ताज़ा इनपुट टोकन। दोनों कैश बकेट को शामिल नहीं करता।

integer

इस अनुरोध द्वारा कैश में लिखे गए टोकन।

integer

कैश से इस अनुरोध को परोसे गए टोकन।

integer

मॉडल द्वारा उत्पन्न टोकन।

integer

तीनों इनपुट बकेट और output_tokens का जोड़। गैर-streaming प्रतिक्रियाओं पर मौजूद।

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

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

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

ठंडा अनुरोध (कैश राइट)

{
  "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"
  }
}

गर्म अनुरोध (कैश रीड)

{
  "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 शब्दार्थ को अपरिवर्तित रिपोर्ट करते हैं। प्रॉम्प्ट गणना पूरा प्रॉम्प्ट है, और कैश्ड टोकन उसका एक उपसमुच्चय हैं जिन्हें अलग से रिपोर्ट किया जाता है।

/v1/chat/completions

{
  "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 के भीतर एक मार्कर रखती हैं:

"sunra_usage_semantics": "anthropic.exclusive.v1"

यह मार्कर प्रतिक्रिया के बारे में एक वादा है, किसी एकल घटना या फ़ील्ड के बारे में नहीं। बिना streaming वाली प्रतिक्रिया में यह मूल usage ऑब्जेक्ट में प्रकट होता है; streaming वाली प्रतिक्रिया में यह message_start में प्रकट होता है, यानी उस घटना में जो इनपुट बकेट लाती है। जब यह इस मान के साथ मौजूद होता है, तो इस पृष्ठ की गारंटियाँ लागू होती हैं: तीनों इनपुट बकेट परस्पर अनन्य हैं, और total_tokens — जहाँ मौजूद हो — उनका जोड़ और output_tokens है। इसकी अनुपस्थिति भी एक वादा है। Sunra केवल उन्हीं प्रतिक्रिया आकारों को सामान्यीकृत करता है जिन्हें उसने मापा है। बाकी सब कुछ अपस्ट्रीम प्रदाता से बिना छेड़छाड़ के अग्रेषित किया जाता है और बिना मार्कर के छोड़ दिया जाता है, और जिस प्रतिक्रिया पर मार्कर नहीं है, उसके बकेट की ज़मानत Sunra नहीं लेता। यह अनुमान लगाने के लिए कि कोई प्रतिक्रिया किस परिपाटी का पालन करती है, संख्याओं का निरीक्षण करने के बजाय मार्कर पर assert करें। आकार सूँघना (shape sniffing) वही है जिसे प्रतिस्थापित करने के लिए यह फ़ील्ड मौजूद है — “बकेट अवश्य अनन्य होंगे क्योंकि उनका जोड़ प्रॉम्प्ट गणना से अधिक है” जैसी युक्ति एक से अधिक परिपाटी से संतुष्ट हो जाती है और अंततः किसी प्रतिक्रिया को ग़लत पढ़ेगी।

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 तिथि के बजाय मार्कर पर आधारित करें, ताकि वही कोड पथ मार्कर वाली और बिना मार्कर वाली दोनों प्रतिक्रियाओं के विरुद्ध सही रहे।

अवलोकन

Multimodal

LLM

क्लाइंट लाइब्रेरी

टोकन उपयोग

Messages

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

Chat Completions और Responses

`sunra_usage_semantics` मार्कर

Streaming

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

​Messages

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

​Chat Completions और Responses

​sunra_usage_semantics मार्कर

​Streaming

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

Messages

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

Chat Completions और Responses

`sunra_usage_semantics` मार्कर

Streaming

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