Skip to content

API क्विक रेफ़रेंस: अनुरोध, प्रतिक्रिया और त्रुटियाँ ​

क्विक स्टार्ट से लेकर परिदृश्य आधारित व्यवहार तक, आप लगातार एक ही चीज़ से निपट रहे हैं: TypeSafe API का /v1/systemone एंडपॉइंट। यह पेज इसे अलग निकालकर एक क्विक रेफ़रेंस तालिका में संकुचित करता है — अनुरोध फ़ील्ड, प्रश्न प्रकार के उत्तर, अनुरोध हेडर, अनुरोध नियम, स्टेटस कोड, सब एक ही तालिका में। कोड लिखते समय यह पेज खुला रखें, यह आधिकारिक API दस्तावेज़ खंगालने से तेज़ है।

सीखने के बाद आप क्या कर सकेंगे ​

  • TypeSafe API के दो एंडपॉइंट, प्रमाणीकरण विधि और अनुरोध बॉडी के चार फ़ील्ड (model / state / questions / assets) बता सकेंगे
  • प्रश्न प्रकार के अनुसार प्रत्येक उत्तर के सटीक रिटर्न फ़ील्ड खोज सकेंगे (Choice / Score / Noul / Box)
  • स्टेटस कोड तालिका से त्रुटियों का पता लगा सकेंगे: 400 से 529 तक प्रत्येक का अर्थ क्या है और क्या बदलना चाहिए
  • जान सकेंगे कि कब TypeSafe-Danger-Zone-* अनुरोध हेडर जोड़ना है और कब खुद रीट्राई लिखना चाहिए
  • SDK की समतुल्य विधियों की तुलना तालिका से Python / JavaScript में वही कॉल पूरा कर सकेंगे

आपकी वर्तमान दुविधा ​

  • कोड लिखते समय हर बार क्विक स्टार्ट पाठ पर लौटकर अनुरोध संरचना कॉपी करनी पड़ती है, एक ऐसा पेज नहीं है जिसमें सीधे खोजा जा सके
  • त्रुटि होने पर केवल एक स्टेटस कोड संख्या पता होती है, यह नहीं पता कि अनुरोध बॉडी ग़लत है या Key
  • curl सीधे कनेक्शन और SDK दोनों तरीके दिमाग़ में टकराते हैं, फ़ील्ड नाम मेल नहीं खाते

इस तरकीब का उपयोग कब करें ​

जब आपको चाहिए:

  • हाथ के पास रखने लायक एक पेज, लिखते ही TypeSafe API के फ़ील्ड और स्टेटस कोड खोजें
  • त्रुटिनिवारण करते समय तेज़ी से तय करें कि "यह 4xx मेरी समस्या है या सेवा की"

और आप नहीं चाहते:

  • हर बार आधिकारिक API संदर्भ का लंबा दस्तावेज़ खंगालना
  • एक ही फ़ील्ड की व्याख्या के लिए कई ट्यूटोरियल पेजों के बीच इधर-उधर भागना

🎒 शुरू करने से पहले की तैयारी ​

मुख्य विचार: एक एंडपॉइंट, सब कुछ अनुरोध संरचना से शुरू ​

Jev सीरीज़ के सभी मॉडल एक ही एंडपॉइंट द्वारा सेव किए जाते हैं: POST https://api.typesafe.ai/v1/systemone। अनुरोध का model फ़ील्ड तय करता है कि किस मॉडल से प्रोसेस होगा — "हर मॉडल के लिए एक अलग URL" जैसी कोई चीज़ नहीं है।

प्रमाणीकरण केवल एक ही हेडर मान्यता देता है:

http
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <你的API Key>
Content-Type: application/json

"कौन से मॉडल उपलब्ध हैं" देखने के लिए एक सहायक एंडपॉइंट भी है:

bash
curl https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

आपको यह दिखना चाहिए: एक models ऐरे, जिसके प्रत्येक आइटम में name, description, release_date शामिल हैं (जैसे jev-latest, General-purpose system one model., 2026-09-15 जैसे उदाहरण मान)। मिले हुए name को सीधे अनुरोध के model फ़ील्ड में भरें।

अनुरोध बॉडी कैसी दिखती है? आधिकारिक क्विक स्टार्ट का टिकट उदाहरण (curl सीधे कनेक्शन संस्करण, दो प्रश्नों का अंश, curl 7.76+ चाहिए, --fail-with-body से त्रुटि होने पर भी प्रतिक्रिया बॉडी प्रिंट होती है):

bash
curl --fail-with-body --silent --show-error \
  https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "state": "Our API integration started returning 500 errors...",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}
JSON

पूरे API की बनावट बस यही है। नीचे इसे भाग-दर-भाग तोड़कर क्विक रेफ़रेंस दिया गया है।

अनुरोध फ़ील्ड की पूरी तालिका ​

फ़ील्डअनिवार्यप्रकारविवरण
model✅स्ट्रिंगमॉडल का नाम या उपनाम; उपलब्ध नाम GET /v1/models से मिलते हैं। जैसे jev-latest, jev-preview
state✅स्ट्रिंग / JSON ऑब्जेक्ट / टेक्स्ट ऐरेसभी प्रश्नों द्वारा संयुक्त रूप से मूल्यांकित सामग्री। तीनों रूपों का विवरण State स्थिति में
questions✅ऑब्जेक्ट (कम से कम 1 प्रश्न)कुंजी आपका चुना हुआ प्रश्न ID है, मान प्रश्न ऑब्जेक्ट है; प्रश्नों की संख्या की कोई ऊपरी सीमा नहीं, सीमा केवल संदर्भ लंबाई पर है
assets❌ऑब्जेक्ट (कम से कम 1 आइटम)इमेज एसेट, की प्लेसहोल्डर है (आधिकारिक सलाह: हर इमेज के लिए एक UUID); इमेज उपयोग करते समय TypeSafe-Danger-Zone-Images: true हेडर अनिवार्य है

समस्या ऑब्जेक्ट के फ़ील्ड:

फ़ील्डअनिवार्यविवरण
ID (ऑब्जेक्ट की की)✅आप स्वयं चुनें, रिस्पॉन्स में जवाब मिलाने के लिए; मॉडल को नहीं भेजा जाता — पूरी समस्या instructions में लिखी जानी चाहिए, भले ही ID स्वतः स्पष्ट लगे
type✅choice / score / noul / box में से एक
instructionsschema में चारों प्रकार की समस्याओं के लिए छोड़ा जा सकता हैपूरी समस्या; स्ट्रिंग, JSON ऑब्जेक्ट या ऐरे हो सकती है (समस्या और उसके द्वारा संदर्भित डेटा अलग हो सकते हैं)। ID मॉडल को नहीं भेजा जाता, इसलिए वास्तव में हर समस्या में इसे लिखना चाहिए
criteriaChoice, Score के लिए अनिवार्यChoice: विकल्पों का map (1–255 आइटम); Score: क्रमबद्ध स्तरों की सूची (1–10 आइटम); Noul: वैकल्पिक true/false हाँ-ना परिभाषाएँ

instructions में state के फ़ील्ड को संदर्भित करने के लिए, डॉट/इंडेक्स पाथ को बैकटिक में रखें, जैसे `ticket.messages[0].text` — विवरण के लिए State स्थिति पाठ देखें।

समस्या प्रकार और उत्तर फ़ील्ड की पूरी तालिका ​

एक अनुरोध में कोई भी समस्या प्रकार मिलाया जा सकता है; सभी समस्याएँ एक ही state पर समानांतर, स्वतंत्र रूप से मूल्यांकित होती हैं (इस उपयोग का चरम उदाहरण समानांतर प्रश्न में देखें)।

समस्या प्रकारtype मानcriteria का रूपउत्तर फ़ील्ड
Choicechoiceविकल्पों का map, 1–255 आइटमchoice (चुने गए विकल्प का नाम, अर्थात सर्वाधिक प्रायिकता वाला आइटम), confidence, probabilities (हर विकल्प के लिए एक प्रायिकता, योग ढीले तौर पर 1 के बराबर)
Scorescoreक्रमबद्ध स्तरों की सूची, 1–10 आइटमscore (प्रायिकता-भारित प्रत्याशित मान, दो स्तरों के बीच आ सकता है, जैसे 0.67 / 1.7), confidence, legend (स्तर से मान का मैपिंग), probabilities
Noulnoulवैकल्पिक: true/false की परिभाषाnoul (0–1 की सत्य/हाँ प्रायिकता; 0.5 के निकट = अनिश्चित; confidence फ़ील्ड नहीं होती)
Boxboxकोई नहींbox (top/bottom/left/right चार किनारे, इमेज की ऊँचाई/चौड़ाई के अनुपात में 0–1), confidence (null हो सकता है)। इमेज + इमेज हेडर सक्रिय आवश्यक

समस्या प्रकार कैसे चुनें, हर एक का पूरा उपयोग:

अनुरोध हेडर की पूरी तालिका ​

अनुरोध हेडरकब उपयोग करेंविवरण
Authorization: Bearer <key>हर अनुरोधअनुपस्थित या अमान्य → 401
Content-Type: application/jsonटेक्स्ट अनुरोधइमेज multipart/form-data से जाती है: JSON पहले भाग के रूप में (नाम request), हर इमेज एक अलग भाग
Content-Encoding: gzip या x-gzip / zstdबड़े अनुरोध बॉडी का कंप्रेशनकेवल एक परत; zstd का window ≤ 8 MiB; असमर्थित या बहु-परत → 415, खराब कंप्रेस्ड बॉडी → 400
TypeSafe-Danger-Zone-Images: trueअनुरोध में इमेज या Box समस्या होने परहर इमेज वाले अनुरोध में अनिवार्य; छूट जाने पर → 400
TypeSafe-Danger-Zone-Long-Context: trueलंबा टेक्स्ट डिफ़ॉल्ट संदर्भ में न समाने परper-request और per-question संदर्भ दोनों 262k हो जाते हैं; कीमत वही, लेकिन अधिक धीमा और कम सटीक, केवल आवश्यक अनुरोधों के लिए उपयोग करें

डिफ़ॉल्ट संदर्भ सीमा (Jev 1.14 और 1.13 समान): प्रति अनुरोध 64k / प्रति समस्या 32k token; समस्याओं की संख्या पर कोई ऊपरी सीमा नहीं। कीमत और मॉडल संस्करण की त्वरित जानकारी मॉडल और कीमत में देखें।

अनुरोध नियम और कंप्रेशन ​

आधिकारिक errors दस्तावेज़ हर अनुरोध के लिए चार कठोर नियम निर्धारित करता है:

नियमसीमाउल्लंघन स्थिति कोड
अनुरोध बॉडी का आकार≤ 32 MiB (header शामिल नहीं)413 (सीमा पार होने पर संपीड़न से पहले और बाद दोनों गिने जाते हैं)
एन्कोडिंगUTF-8 JSON, BOM के बिना400
नेस्टिंगstate / instructions / criteria प्रत्येक ≤ 64 परतें ऑब्जेक्ट और ऐरे की; इससे गहरे पहले फ्लैट करें400
संख्याएँकेवल परिमित संख्याएँ स्वीकार्य हैं: NaN, Infinity, 1e400 जैसी सब अस्वीकृत होंगी; बड़ी संख्याएँ और ID स्ट्रिंग में भेजें400

संपीड़न में केवल दो अतिरिक्त शर्तें हैं: एक परत की सीमा, और zstd window ≤ 8 MiB।

रिस्पॉन्स फ़ील्ड की पूरी तालिका ​

json
{
  "model": "jev-1.14.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 1.0,
      "probabilities": { "technical": 1.0, "billing": 0.0, "sales": 0.0 }
    },
    "frustration": {
      "type": "score",
      "score": 0.67,
      "confidence": 0.5,
      "legend": { "0": "Calm…", "1": "Frustrated…", "2": "Very angry…" },
      "probabilities": { "0": 0.33, "1": 0.67, "2": 0.0 }
    },
    "is_urgent": { "type": "noul", "noul": 0.99 }
  },
  "usage": { "input_tokens": 428, "output_tokens": 73 }
}

(उदाहरण मान, संस्करण के साथ बदलेंगे; पूरा उदाहरण देखें पहला अनुरोध पाठ में।)

फ़ील्डस्थानविवरण
modelशीर्ष स्तरवास्तविक उत्तर देने वाले मॉडल का नाम; अनुरोध में दिए उपनाम से भिन्न हो सकता है (जैसे अनुरोध jev-latest, लौटाया गया विशिष्ट संस्करण संख्या)
answersशीर्ष स्तरआपके दिए प्रश्न ID के अनुसार एक-एक मिलाए गए; प्रत्येक प्रश्न का type उसके प्रश्न के type से संगत होता है
usage.input_tokensशीर्ष स्तरइस बार बिल किए गए इनपुट टोकन की संख्या (बिलिंग में केवल इनपुट गिना जाता है)
usage.output_tokensशीर्ष स्तरआउटपुट टोकन की संख्या, वर्तमान में निःशुल्क

स्थिति कोड की पूरी तालिका ​

स्थिति कोडअर्थआपको क्या करना चाहिए
200सफलID से उत्तर लें
400 Bad Requestअनुरोध नियमों का उल्लंघन (अवैध UTF-8, 64 परतों से अधिक नेस्टिंग, अपरिमित संख्या, खराब संपीड़ित बॉडी, छूटा हुआ इमेज हेडर); max_tokens_exceeded = संदर्भ लंबाई से अधिक“अनुरोध नियम” तालिका से मिलाकर अनुरोध बॉडी ठीक करें; संदर्भ सीमा पार हो तो state हल्का करें या लॉन्ग-कॉन्टेक्स्ट हेडर चालू करें
401 UnauthorizedKey अनुपस्थित या अमान्यAuthorization हेडर जाँचें; SDK उपयोगकर्ता TYPESAFE_API_KEY जाँचें (नीचे सावधानी अनुभाग देखें)
413 Payload Too Largeअनुरोध बॉडी 32 MiB से अधिकstate घटाएँ; संपीड़न मदद नहीं करेगा 413 — 32 MiB सीमा संपीड़न से पहले और बाद दोनों पर लागू होती है
415 Unsupported Media TypeContent-Encoding असमर्थित या संपीड़न की कई परतेंकेवल gzip / x-gzip / zstd में से एक, एक परत
422 Unprocessable Entityअनुरोध बॉडी सत्यापन विफल: अनिवार्य फ़ील्ड अनुपस्थित, प्रश्न का प्रारूप गलत, आदिbody के detail ऐरे से स्थान पहचानें
429 Too Many Requestsरेट सीमा पार (संगठन के अनुसार: tokens/s + requests/s, कंसोल console.typesafe.ai/rate-limits पर देखें)एक्सपोनेंशियल बैकऑफ़ से पुनः प्रयास करें; SDK डिफ़ॉल्ट रूप से स्वतः संभालता है
529 OverloadedTypeSafe अस्थायी ओवरलोड429 जैसा ही: बैकऑफ़ के बाद पुनः प्रयास

422 का body फ़ील्ड तक सटीक होता है:

json
{
  "detail": [
    { "loc": ["body", "state"], "msg": "Field required", "type": "missing" }
  ]
}

loc से त्रुटिपूर्ण फ़ील्ड खोजें, msg बताता है कि क्या छूट गया।

त्रुटि हैंडलिंग और पुनः प्रयास ​

आधिकारिक नियम एक वाक्य में: 429 या 529 मिलने पर, एक्सपोनेंशियल बैकऑफ़ से पुनः प्रयास करें (हर बार प्रतीक्षा बढ़ाते हुए), तुरंत वैसा ही दोबारा न भेजें; रिस्पॉन्स में retry-after हेडर हो तो उसका पालन करें।

SDK का उपयोग करने वाले आप: Python / JavaScript SDK में डिफ़ॉल्ट रूप से पुनः प्रयास की नीति शामिल है, जो 429 को स्वतः संभालती है, अतिरिक्त कोड की आवश्यकता नहीं। अनुकूलन चाहिए तो (Python):

python
from typesafe_sdk import RetryPolicy, TypeSafeClient

client = TypeSafeClient(retry=RetryPolicy(max_retries=3, backoff_max=0.2, timeout=1.0))

Python SDK में API त्रुटियाँ पकड़ने का मानक तरीका:

python
from typesafe_sdk import TypeSafeAPIError

try:
    client.system_one(state, questions)
except TypeSafeAPIError as error:
    print(error.status, error.request_id)

error.status स्थिति कोड है, error.request_id अनुरोध पहचानकर्ता है — आधिकारिक सहायता को रिपोर्ट करते समय इन्हें साथ दें।

सीधे API से जुड़ने वाले आप: पुनः प्रयास स्वयं लिखने होंगे। curl का --fail-with-body कम से कम यह सुनिश्चित करता है कि त्रुटि पर रिस्पॉन्स बॉडी दिखे।

Python के दो क्लाइंट की संक्षिप्त जानकारी ​

TypeSafe API के दोनों Python क्लाइंट पर विधियों के नाम समान हैं: TypeSafeClient (सिंक्रोनस) और AsyncTypeSafeClient (असिंक्रोनस), दोनों system_one() हैं। SDK पढ़ने वाले पर्यावरण चर:

चरउद्देश्यडिफ़ॉल्ट
TYPESAFE_API_KEYAPI Key (अनिवार्य)—
TYPESAFE_BASE_URLAPI का मूल URLhttps://api.typesafe.ai
TYPESAFE_DEFAULT_MODELडिफ़ॉल्ट मॉडलjev-latest
TYPESAFE_LOG_LEVELtypesafe_sdk लॉग स्तर, import के समय एक बार लागूसेट नहीं

TypeScript उत्तरों की संक्षिप्त जानकारी ​

JS/TS SDK (@typesafe-ai/sdk) में उत्तर ID से सीधे लिए जाते हैं: response.answers.department.choice, और प्रकार प्रश्न की परिभाषा से अनुमानित होता है (जैसे "billing" | "technical" | "sales")।

सावधानी अनुभाग ​

❌ अनुरोध jev-latest, पर प्रतिक्रिया में model वही नहीं है ​

यह त्रुटि नहीं है——प्रतिक्रिया का model वास्तव में उत्तर देने वाले मॉडल का नाम है, जो अनुरोध में दिए गए उपनाम से भिन्न हो सकता है (आधिकारिक API विनिर्देश में यह स्पष्ट रूप से बताया गया है)। उपनाम का वर्तमान संकेतन देखें मॉडल और मूल्य।

❌ Key में खाली स्थान या लाइन ब्रेक मिल गया ​

सीधे कनेक्ट करने पर ऐसी Key हमेशा 401 देती है। SDK, Key के आरंभ और अंत की खाली जगहें (फ़ाइल से पढ़ी गई लाइन ब्रेक सहित) हटा देता है, लेकिन आंतरिक खाली स्थान, नियंत्रण वर्ण, गैर-ASCII सीधे अस्वीकार कर दिए जाते हैं (क्लाइंट बनाते समय ही त्रुटि मिलती है, 401 तक पहुंचता ही नहीं); स्पष्ट रूप से खाली Key देने पर environment variable पर वापस नहीं जाता। कंसोल से Key कॉपी करते समय एक अतिरिक्त खाली स्थान मत चुनें।

❌ 422 के स्टेटस कोड से अंदाज़ा लगाना कि कहां गड़बड़ है ​

अंदाज़ा मत लगाइए, body पढ़ें: detail सरणी का loc ही फ़ील्ड पथ है (जैसे ["body", "questions", "urgency", "criteria"]), msg कारण है।

❌ Noul के उत्तर में confidence नहीं मिलता ​

खोया नहीं है——Noul में स्वाभाविक रूप से confidence फ़ील्ड नहीं होता। एक समान सीमा चाहिए तो स्वयं |2p − 1| निकालें, आधिकारिक सुझाव शुरुआती बिंदु: yes ≥ 0.7, no ≤ 0.3 (देखें Noul हां-ना प्रश्न)।

❌ सीधे API को बार-बार कॉल करने पर 429 से स्क्रीन भर जाती है ​

रेट लिमिट संगठन के हिसाब से गिना जाता है (tokens/s + requests/s)। SDK डिफ़ॉल्ट रूप से बैकऑफ़ के साथ पुनः प्रयास करता है; सीधे कनेक्ट करें तो स्वयं घातीय बैकऑफ़ लिखें। उच्च सीमा के लिए आधिकारिक आवेदन फ़ॉर्म (support.typesafe.ai) का उपयोग करें।

इस पाठ का सारांश ​

✅ एक एंडपॉइंट POST /v1/systemone, प्रमाणीकरण एक हेडर, अनुरोध बॉडी में चार फ़ील्ड (model / state / questions / assets)।

✅ चार प्रश्न प्रकार, चार उत्तर: Choice विकल्प + प्रायिकता + confidence देता है, Score अपेक्षित अंक + legend देता है, Noul केवल 0–1 प्रायिकता देता है, Box चारों किनारों का अनुपात देता है।

✅ स्टेटस कोड की पूरी श्रृंखला: 400 नियम / 401 Key / 413 आकार / 415 संपीड़न / 422 सत्यापन (body देखें) / 429 529 बैकऑफ़ पुनः प्रयास।

✅ दो Danger Zone हेडर आवश्यकतानुसार जोड़ें: छवियों के लिए TypeSafe-Danger-Zone-Images, लंबे संदर्भ के लिए TypeSafe-Danger-Zone-Long-Context।

मुख्य कॉन्फ़िगरेशन फ़ील्ड की समीक्षा:

फ़ील्डअनुशंसित मानविवरण
modeljev-latestउपनाम, वर्तमान में Jev 1.14 की ओर संकेत; संस्करण लॉक करना हो तो jev-1.14.0 लिखें
stateस्ट्रिंग / JSON ऑब्जेक्ट / टेक्स्ट सरणीतीनों रूपों में से कोई भी चुनें
questions{ID: {type, instructions, criteria}}ID मॉडल को नहीं भेजा जाता; पूरा प्रश्न instructions में लिखें
संदर्भ64k / अनुरोध · 32k / प्रश्नलंबा संदर्भ हेडर जोड़ने के बाद दोनों 262k
अनुरोध बॉडीUTF-8 JSON ≤ 32 MiB · नेस्टिंग ≤ 64 स्तर · संख्याएँ अनिवार्यतः परिमित होंसंपीड़न एक स्तर तक gzip / zstd

अगले पाठ की झलक ​

API चलाना आ गया, अब हिसाब भी समझना होगा: मॉडल और मूल्य: संस्करण, संदर्भ सीमाएँ, दरें।

आप सीखेंगे:

  • jev-1.14.0 और jev-1.13.0 की संस्करण समयरेखा तथा उपनाम संकेतन
  • $42/Btok का बिलिंग तरीका: क्यों केवल इनपुट token गिने जाते हैं
  • संदर्भ सीमाओं की बारीकियाँ और लंबे संदर्भ की कीमत
  • रेट लिमिट कैसे देखें, सीमा वृद्धि के लिए आवेदन कैसे करें

संबंधित ट्यूटोरियल ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.