दस्तऐवज

रूटिंग & डेटा रेसिडेन्सी

कॅटलॉगमधील बहुतेक मॉडेल्ससाठी एकापेक्षा अधिक 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; डेटा रेसिडेन्सी