शुरुआत करें

अवलोकन

यह उदाहरण web_search से कुंजी तैयार करने, मुफ़्त कोटेशन लेने, चलाने और नतीजा लेने तक जाता है। किसी भाषा-विशिष्ट SDK के बिना Bash-संगत शेल और cURL पर्याप्त हैं।

पहले की तैयारी

ये पाँच चीज़ें तैयार रखें:

Developer Platform में साइन इन कर सकने वाला NoimosAI खाता
API पहुँच चालू वाला Developer Platform प्रोजेक्ट
nmp_ से शुरू होने वाली डेवलपर कुंजी और आवश्यक अनुमतियाँ
Bash-संगत शेल
cURL, jq और uuidgen

सशुल्क निष्पादन के लिए प्रोजेक्ट का प्रीपेड USD बैलेंस और मासिक सीमाएँ भी जाँचें। कुंजी अनुमतियाँ अनुरोध प्रमाणित करें में हैं। यदि कोई उपलब्ध प्रोजेक्ट न दिखे, संगठन के OWNER या ADMIN से प्रोजेक्ट बनाने या सदस्यता देने को कहें। कुंजियाँ अपने सदस्यता वाले प्रोजेक्ट में बनाएँ।

API चलाएँ

पहले निष्पादन के लिए ये सात चरण अपनाएँ।

1. Developer Platform में कुंजी बनाएँ

प्रोजेक्ट का ADMIN या DEVELOPER, Developer Platform में कुंजी बना सकता है:

साइन इन करके प्रोजेक्ट चुनें।
API कुंजियाँ खोलें और नई कुंजी बनाएँ चुनें।
स्पष्ट नाम, समाप्ति और अनुमतियाँ तय करके कुंजी बनाएँ।
केवल एक बार दिखने वाली गुप्त कुंजी सुरक्षित जगह रखें।

इस गाइड के लिए project:read, tools:read, tools:execute और executions:read चाहिए। अन्य उपयोगों के लिए केवल आवश्यक अनुमतियाँ दें।

2. कुंजी और बेस URL सेट करें

कुंजी और बेस URL को एनवायरनमेंट वेरिएबल में रखें ताकि गोपनीय जानकारी सीधे कमांड इतिहास या सोर्स कोड में न लिखी जाए।

export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."

कुंजी केवल बनाते समय दिखती है। इसे Git, साझा दस्तावेज़ या क्लाइंट JavaScript में न रखें।

3. कुंजी का प्रोजेक्ट जाँचें

पहले सुनिश्चित करें कि कुंजी सही Developer Platform प्रोजेक्ट से जुड़ी है।

curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/project" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY"

सफल उत्तर के data में संगठन ID, प्रोजेक्ट ID और नाम मिलते हैं। प्रोजेक्ट अपेक्षित न हो तो सशुल्क काम से पहले कुंजी जाँचें।

{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}

4. उपलब्ध टूल देखें

वर्तमान नाम, विवरण, इनपुट स्कीमा, उदाहरण, उपलब्धता और कीमतें लें।

NOIMOS_TOOLS_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

echo "$NOIMOS_TOOLS_RESPONSE" | jq

पूरे उत्तर का executionEnabled और टूल का available जाँचें। टूल संख्या, मॉडल, स्कीमा या कीमत स्थिर न मानें; इस उत्तर को वर्तमान आधार बनाएँ। केवल web_search देखने के लिए सहेजे उत्तर को फ़िल्टर करें।

echo "$NOIMOS_TOOLS_RESPONSE" | jq \
  '.data.tools[] | select(.name == "web_search") | {
    name,
    description,
    available,
    inputSchema,
    example,
    models,
    price
  }'

5. चलाने से पहले कोटेशन लें

टूल का नाम और आर्ग्युमेंट भेजकर मूल्य संस्करण और अधिकतम आरक्षित रकम लें। इससे सशुल्क काम शुरू नहीं होता।

NOIMOS_QUOTE_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/quote" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "tool": "web_search",
    "arguments": {
      "query": "content marketing trends",
      "count": 5
    }
  }')

echo "$NOIMOS_QUOTE_RESPONSE" | jq

कोटेशन में निष्पादन के लिए priceVersion और maximumChargeMicros मिलते हैं। बिना अपनी गणना या बदलाव के इन्हीं को दोबारा इस्तेमाल करें। maximumChargeMicros USD के दस लाखवें हिस्से में पूर्णांक है: 1 USD बराबर 1,000,000 micros।

{
  "data": {
    "tool": "web_search",
    "priceVersion": "...",
    "currency": "usd",
    "minimumChargeMicros": 0,
    "maximumChargeMicros": 0,
    "expiresAt": "..."
  }
}

ऊपर की रकम केवल उत्तर का प्रारूप दिखाती है। अगला चरण सहेजे उत्तर से वास्तविक मान लेता है।

6. कोटेशन वाला अनुरोध चलाएँ

वही टूल और आर्ग्युमेंट रखें और मिला मूल्य संस्करण तथा अधिकतम आरक्षित रकम जोड़ें। इस तार्किक अनुरोध की पहचान के लिए एक इडेम्पोटेंसी कुंजी दें।

export NOIMOS_PRICE_VERSION=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.priceVersion')
export NOIMOS_MAXIMUM_CHARGE_MICROS=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.maximumChargeMicros')
export NOIMOS_IDEMPOTENCY_KEY=$(uuidgen)

NOIMOS_EXECUTION_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/web_search" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NOIMOS_IDEMPOTENCY_KEY" \
  --data "$(jq -n \
    --arg priceVersion "$NOIMOS_PRICE_VERSION" \
    --argjson maximumChargeMicros "$NOIMOS_MAXIMUM_CHARGE_MICROS" \
    '{
      tool: "web_search",
      arguments: {
        query: "content marketing trends",
        count: 5
      },
      priceVersion: $priceVersion,
      maximumChargeMicros: $maximumChargeMicros
    }')")

echo "$NOIMOS_EXECUTION_RESPONSE" | jq
export NOIMOS_EXECUTION_ID=$(echo "$NOIMOS_EXECUTION_RESPONSE" | jq -r '.data.id')

यह उदाहरण चरण 5 का कोटेशन इस्तेमाल करके uuidgen से कुंजी बनाता है। स्वीकृति पर HTTP 202 और निष्पादन ID मिलते हैं।

{
  "data": {
    "id": "EXECUTION_ID",
    "tool": "web_search",
    "status": "queued",
    "reservedMicros": 0,
    "chargedMicros": 0
  }
}

उत्तर में मूल्य संस्करण, आउटपुट, त्रुटियाँ और समय भी हैं। प्रोसेस के दौरान chargedMicros: 0 का अर्थ अंतिम शुल्क मुफ़्त होना नहीं है।

7. उसी निष्पादन ID से स्थिति पूछें

चरण 6 का ID लेकर पूरा होने तक कम से कम पाँच सेकंड के अंतराल पर पूछें।

while true; do
  NOIMOS_STATUS_RESPONSE=$(curl --fail-with-body \
    "$NOIMOS_PLATFORM_API_URL/tools/executions/$NOIMOS_EXECUTION_ID" \
    -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

  echo "$NOIMOS_STATUS_RESPONSE" | jq
  NOIMOS_STATUS=$(echo "$NOIMOS_STATUS_RESPONSE" | jq -r '.data.status')

  case "$NOIMOS_STATUS" in
    succeeded|failed|cancelled|needs_review) break ;;
  esac

  sleep 5
done

queued, running और waiting का अर्थ प्रक्रिया जारी है। succeeded पर output और chargedMicros पढ़ें। अन्य स्थितियाँ निष्पादन और बिलिंग सँभालें में हैं।

उत्तर अज्ञात हो तो नई इडेम्पोटेंसी कुंजी से दोबारा न भेजें। वही बॉडी और कुंजी पहले स्वीकार किए गए निष्पादन को वापस देती हैं।