दस्तावेज़

रूटिंग & डेटा रेज़िडेंसी

कैटलॉग में अधिकतर मॉडल में एक से अधिक provider रूट होते हैं। प्रत्येक रिक्वेस्ट पर गेटवे स्वस्थ, योग्य रूट्स के बीच चुनाव करता है — price के आधार पर, जब तक आप अन्यथा न कहें — फिर यदि चुना गया provider एरर करता है तो अपने-आप फेलओवर कर देता है। आप इसे चार वैकल्पिक रिक्वेस्ट फ़ील्ड्स के साथ नियंत्रित करते हैं, जो दोनों/v1/chat/completions और /v1/embeddings पर स्वीकार किए जाते हैं। ये BharatRouter एक्सटेंशन हैं: राउटर इन्हें उपयोग करता है और कुछ भी अपस्ट्रीम फॉरवर्ड करने से पहले इन्हें हटा देता है, ताकि providers इन्हें कभी न देखें।

रिक्वेस्ट एक्सटेंशन

फ़ील्ड	मान	यह क्या करता है
`optimize`	`price` (default) · `latency` · `uptime` · `throughput` · `auto`	योग्य providers के बीच रूट-चयन प्राथमिकता। `price` input + output ₹/Mtok के योग के आधार पर रैंक करता है (केवल input नहीं)। `latency` प्रति रूट देखी गई latency का एक मूविंग एवरेज उपयोग करता है; `uptime` देखी गई विफलता दर के आधार पर सॉर्ट करता है; `throughput` उन रूट्स को प्राथमिकता देता है जिनमें rate-limit हेडरूम और कम latency हो — यह लोड के समय अपनी सीमा के पास पहुँच रहे providers से ट्रैफ़िक हटाता है, निरंतर गति के लिए थोड़ा अधिक चुकाते हुए; `auto` सबको मिलाता है (विश्वसनीयता पहले, फिर latency/price ट्रेड-ऑफ)। नोट: मोड कुछ भी हो, जिन रूट्स का सर्किट खुला है उन्हें हमेशा आखिर में आज़माया जाता है — इसलिए कैटलॉग का सबसे सस्ता रूट तब छोड़ा जा सकता है जब वह वर्तमान में अस्वस्थ हो, यही कारण है कि एक `price` रिक्वेस्ट एकल सबसे सस्ते provider पर नहीं उतर सकती।
`optimize_weights`	object, जैसे `{"latency":1,"throughput":1,"price":0.2}`	स्पष्ट डायल — किसी नामित मोड के बजाय चारों axes (`price`, `latency`, `uptime`, `throughput`) को सीधे वज़न दें। मौजूद होने पर यह `optimize` को ओवरराइड करता है। हर वज़न एक गैर-ऋणात्मक संख्या है; अनुपस्थित या शून्य axis blend से हट जाता है, और गलत/ऋणात्मक मान 0 माना जाता है — इसलिए एक खराब डायल रैंकिंग को सपाट करने के बजाय सुरक्षित रूप से नामित मोड पर लौट आता है। तब उपयोग करें जब कोई एक नामित मोड आपके इच्छित ट्रेड-ऑफ़ को न पकड़े (जैसे "तेज़ और असंतृप्त, हल्के लागत-टाईब्रेक के साथ")।
`provider`	a provider id, e.g. `krutrim`, `sarvam`, `bharatrouter`	एक provider को पिन करें और पूरी तरह से डायनेमिक रूटिंग छोड़ दें। Provider ids `GET /v1/providers` पर सूचीबद्ध हैं।
`data_policy`	`india_only`	केवल भारत-निवासी रूट्स ही योग्य हैं। यदि मॉडल के लिए कोई मौजूद नहीं है, तो रिक्वेस्ट `no_route` के साथ विफल हो जाती है — यह कभी भी चुपचाप भारत नहीं छोड़ती।
`exclude`	array of provider ids, e.g. `["openai"]`	इन providers को रूटिंग से हटा दें। `provider/model` (उदाहरण के लिए `"openai/gpt-5"`) के रूप में एक एंट्री केवल उस एक मॉडल के लिए उस provider को बाहर करती है — फॉलबैक चेन के भीतर उपयोगी। `data_policy` जैसा एक हार्ड फ़िल्टर: यदि यह पूल को खाली कर देता है तो रिक्वेस्ट `no_route` के साथ विफल हो जाती है।
`upstream_key`	your provider API key	प्रति-रिक्वेस्ट BYOK: कॉल आपकी key और आपके provider बिलिंग पर चलती है। कभी संग्रहीत या लॉग नहीं किया जाता। BYOK देखें।

वास्तव में उपयोग किया गया रूट प्रत्येक जवाब पर x-br-provider रिस्पांस हेडर में रिपोर्ट किया जाता है, चाहे स्ट्रीम किया गया हो या नहीं।

उदाहरण: सबसे सस्ता भारत-निवासी रूट

from openai import OpenAI
client = OpenAI(base_url="https://api.bharatrouter.com/v1", api_key="br-...")

r = client.chat.completions.create(
    model="qwen3-32b",
    messages=[{"role": "user", "content": "Summarise this complaint in Hindi: ..."}],
    extra_body={"optimize": "price", "data_policy": "india_only"},
)

उदाहरण: एक provider को पिन करें

curl https://api.bharatrouter.com/v1/chat/completions \
  -H "Authorization: Bearer br-..." -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4-e4b-it",
    "provider": "krutrim",
    "messages": [{"role": "user", "content": "namaste"}]
  }'

उदाहरण: एक provider को बाहर करें

curl https://api.bharatrouter.com/v1/chat/completions \
  -H "Authorization: Bearer br-..." -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "exclude": ["openai"],
    "messages": [{"role": "user", "content": "namaste"}]
  }'

india_only कैसे काम करता है

कैटलॉग में प्रत्येक रूट एक रेज़िडेंसी टैग वहन करता है। data_policy: "india_only"चयन और फेलओवर से पहले उम्मीदवार सेट को भारत-निवासी रूट्स तक फ़िल्टर करता है, ताकि गारंटी फेलओवर के दौरान भी बनी रहे: एक रिक्वेस्टno_route (HTTP 400) के साथ विफल हो सकती है लेकिन इसे भारत के बाहर से नहीं परोसा जा सकता। यह DPDP-संवेदनशील वर्कलोड के लिए प्रवर्तन बिंदु है — इसे नीति दस्तावेज़ में नहीं, बल्कि रिक्वेस्ट में डालें।

फेलओवर & सर्किट ब्रेकर

यदि चयनित provider विफल रहता है, तो गेटवे all_routes_failed (HTTP 502) के साथ हार मानने से पहले प्राथमिकता क्रम में शेष योग्य रूट्स को पुनः प्रयास करता है। हेल्थ को प्रति रूट ट्रैक किया जाता है:

क्या विफलता मानी जाती है (फेलओवर ट्रिगर करती है): एक कनेक्शन/नेटवर्क एरर, या एक अपस्ट्रीम 5xx, 429 (rate limit),401 या 403। गेटवे अगले चरण पर चला जाता है।
क्या फेलओवर ट्रिगर नहीं करता: एक क्लाइंट-साइड 4xx(जैसे 400 खराब रिक्वेस्ट, 404, 422) आपकी रिक्वेस्ट की समस्या है, रूट की नहीं — इसे आपको वैसे ही लौटा दिया जाता है, अपरिवर्तित, और चेन रुक जाती है। एक खराब रिक्वेस्ट को चुपचाप किसी भिन्न provider के विरुद्ध पुनः प्रयास नहीं किया जाएगा (जो बस उसी तरह विफल होगा और आपकी latency में वृद्धि करेगा)।
प्रति रूट latency और विफलता दर का एक मूविंग एवरेजoptimize: latency और optimize: uptime मोड को फीड करता है।
3 लगातार विफलताओं के बाद एक रूट का सर्किट खुल जाता है और यह ट्रैफिक प्राप्त करना बंद कर देता है; 30 सेकंड के बाद एक हाफ-ओपन प्रोब एक रिक्वेस्ट को जाने देता है, और सफलता सर्किट को फिर से बंद कर देती है।
एक BYOK key पर होने वाली विफलताएं उस key के लिए जिम्मेदार ठहराई जाती हैं, न कि रूट के लिए — आपकी समाप्त हुई key एक स्वस्थ provider को सभी के लिए डाउन के रूप में चिह्नित नहीं करती।

दो अलग "यह काम नहीं किया" प्रतिक्रियाएं

ये जानबूझकर अलग हैं — वे आपको बताते हैं कि रिक्वेस्ट कहाँ रुकी:

no_route (HTTP 400) — pre-flight: कोई योग्य रूट हल भी नहीं किया जा सका, इसलिए कुछ भी डायल नहीं किया गया। कारण: एक मॉडल जिसमें कोई कॉन्फ़िगर्ड provider नहीं है, data_policy: india_only जिसमें कोई भारत रूट नहीं है, एक पिन किया गया provider जो मॉडल को सेवा नहीं देता, या एक चेन जिसका हर चरण अनसुलझा है।
all_routes_failed (HTTP 502) — runtime: रूट्स मौजूद थे और कोशिश की गई, लेकिन हर एक विफल रहा (ऊपर दिए गए विफलता नियमों के अनुसार)।
model_not_found (HTTP 404) — मॉडल id कैटलॉग में नहीं है और यह एक खोज योग्य provider/model BYOK id नहीं है।

Reasoning मॉडल & `max_tokens`

Reasoning मॉडल (कैटलॉग में reasoning टैग किए गए — जैसेgpt-oss-120b, qwen3 परिवार, gpt-5) दृश्यमान उत्तर से पहलेकंप्लीशन बजट का हिस्सा छिपे हुए reasoning पर खर्च करते हैं। इसलिए एक बहुत छोटा max_tokensपूरी तरह से reasoning द्वारा उपभोग किया जा सकता है, जिससे content खाली रह जाता है। उस फुटगन से बचने के लिए, गेटवे एक बहुत छोटे max_tokens को केवल reasoning मॉडल के लिए512 के फ्लोर तक बढ़ा देता है, और इसेx-br-reasoning-min-tokens रिस्पांस हेडर में रिपोर्ट करता है। एक अनसेट max_tokens को वैसे ही छोड़ दिया जाता है (provider डिफ़ॉल्ट पहले से ही reasoning-जागरूक है)। थिंकिंग ट्रेस, जब कोई provider इसे लौटाता है, एक अलग reasoning_content फ़ील्ड में आता है, न किcontent में।

लाइव सर्किट स्थिति GET /health पर सार्वजनिक है, और प्रति-मॉडल 7-दिवसीय आँकड़ेGET /v1/models/:id/stats पर हैं।

सहेजे गए फॉलबैक चेन्स

प्रति-रिक्वेस्ट रूटिंग से परे आप एक मॉडल के लिए एक फॉलबैक चेन सहेज सकते हैं — चरणों की एक क्रमबद्ध सूची जो आपके पूरे org के लिए उस मॉडल की डिफ़ॉल्ट रूटिंग को बदल देती है। एक चरण { model, provider? } है (एक नंगी स्ट्रिंग{ model } के लिए शॉर्टहैंड है), और चेन्स क्रॉस-मॉडल फर्स्ट-क्लास हैं: "मेरा खुद का GPU → Krutrim → OpenRouter" एक वैध चेन है। वही JSON आकार हर जगह उपयोग किया जाता है — REST, MCP, और डैशबोर्ड।

1–10 चरण। model एक कैटलॉग id है या एकprovider/model-id BYOK id।
provider एक कैटलॉग provider id है (देखें GET /v1/providers) या एकbyoe:<slug> कस्टम एंडपॉइंट।
ऐसे चरण जो अभी तक हल नहीं हुए (एक BYOK key सहेजी नहीं गई, एक BYOE एंडपॉइंट पंजीकृत नहीं) रिक्वेस्ट के समय छोड़ दिए जाते हैं, बजाय इसके कि चेन विफल हो।

PUT /me/routing/llama-3.1-8b-instruct
{ "steps": [
    { "model": "llama-3.1-8b-instruct", "provider": "bharatrouter" },
    { "model": "llama-3.1-8b-instruct", "provider": "krutrim" },
    { "model": "mistral/mistral-large-latest" }
] }
→ { "ok": true, "model": "llama-3.1-8b-instruct", "steps": [ ... ] }   // effective within a minute

एंडपॉइंट	यह क्या करता है
`GET /me/routing`	अपने org की सहेजी गई चेन्स की सूची बनाएं।
`GET /me/routing/:model`	एक मॉडल के लिए चेन प्राप्त करें।
`PUT /me/routing/:model`	चेन को सहेजें या बदलें (owner/admin)।
`DELETE /me/routing/:model`	इसे हटा दें — रूटिंग डिफ़ॉल्ट पर वापस आ जाती है (owner/admin)।

एक प्रति-रिक्वेस्ट fallbacks array (वही चरण आकार, chat/embeddings बॉडी पर) उस एकल कॉल के लिए सहेजी गई चेन को ओवरराइड करता है। चेन्स कोcollections के रूप में साझा और पुन: उपयोग किया जा सकता है, और चरण आपके अपनेपंजीकृत एंडपॉइंट्स पर इंगित कर सकते हैं। एजेंट्स चेन्स का प्रबंधनMCP पर get_fallback_chains,set_fallback_chain और clear_fallback_chain के साथ करते हैं।

स्ट्रीमिंग & मीटरिंग

स्ट्रीम किए गए रिक्वेस्ट के लिए गेटवे stream_options.include_usageको उन providers पर इंजेक्ट करता है जो इसका समर्थन करते हैं, और अंतिम SSE चंक से यूसेज ब्लॉक को पार्स करता है — इसलिए स्ट्रीम किए गए और गैर-स्ट्रीम किए गए रिक्वेस्ट को समान रूप से मीटर किया जाता है, और आपकेक्रेडिट डेबिट हमेशा वास्तविक टोकन गणना को दर्शाते हैं।

रूटिंग &amp; डेटा रेज़िडेंसी