Pierwsze kroki

Przegląd

Przykład z web_search prowadzi od przygotowania klucza przez bezpłatną wycenę do wykonania i wyniku. Wystarczą powłoka zgodna z Bash i cURL, bez SDK dla konkretnego języka.

Wymagania

Przygotuj pięć elementów:

Konto NoimosAI z dostępem do Developer Platform
Projekt Developer Platform z włączonym API
Klucz deweloperski z prefiksem nmp_ i wymaganymi uprawnieniami
Powłoka zgodna z Bash
cURL, jq i uuidgen

Do płatnego wykonania sprawdź też przedpłacone saldo USD i miesięczne limity projektu. Uprawnienia opisuje Uwierzytelnianie żądań. Jeśli nie widać dostępnego projektu, poproś OWNER lub ADMIN organizacji o utworzenie projektu albo dodanie członkostwa. Klucze tworzysz w projekcie, do którego należysz.

Uruchomienie API

Pierwsze wykonanie obejmuje siedem kroków.

1. Utwórz klucz w Developer Platform

ADMIN lub DEVELOPER projektu może utworzyć klucz w Developer Platform:

Zaloguj się i wybierz projekt.
Otwórz Klucze API i wybierz Utwórz nowy klucz.
Ustaw opisową nazwę, ważność i uprawnienia, a następnie utwórz klucz.
Zapisz sekret w bezpiecznym miejscu; jest wyświetlany tylko raz.

Ten przewodnik wymaga project:read, tools:read, tools:execute i executions:read. Do innych zastosowań wybierz tylko niezbędne uprawnienia.

2. Ustaw klucz i bazowy URL

Zapisz klucz i bazowy URL w zmiennych środowiskowych, aby nie umieszczać sekretów bezpośrednio w historii poleceń lub kodzie.

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

Klucz pojawia się tylko przy tworzeniu. Nie zapisuj go w Git, dokumentach współdzielonych ani JavaScript po stronie klienta.

3. Sprawdź projekt klucza

Najpierw sprawdź, czy klucz łączy się z właściwym projektem Developer Platform.

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

Odpowiedź zawiera w data ID organizacji, ID i nazwę projektu. Jeśli projekt jest inny, sprawdź klucz przed płatną operacją.

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

4. Sprawdź dostępne narzędzia

Pobierz aktualne nazwy, opisy, schematy, przykłady, dostępność i ceny.

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

echo "$NOIMOS_TOOLS_RESPONSE" | jq

Sprawdź executionEnabled całej odpowiedzi oraz available narzędzia. Traktuj odpowiedź jako aktualne źródło, nie zakładając stałej liczby narzędzi, modeli, schematów lub cen. Przefiltruj zapisaną odpowiedź, aby zobaczyć tylko web_search.

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

5. Pobierz wycenę przed wykonaniem

Wyślij nazwę narzędzia i argumenty, aby otrzymać wersję cen oraz maksymalną rezerwację. Nie rozpoczyna to płatnego zadania.

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

Wycena zwraca priceVersion i maximumChargeMicros potrzebne do wykonania. Użyj ich bez zmian i własnych obliczeń. maximumChargeMicros to liczba całkowita w milionowych częściach USD: 1 USD to 1,000,000 micros.

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

Powyższe kwoty ilustrują tylko format. Następny krok odczytuje rzeczywiste wartości z zapisanej odpowiedzi.

6. Wykonaj wycenione żądanie

Zachowaj narzędzie i argumenty wyceny, dodając wersję cen i maksymalną rezerwację. Dołącz klucz idempotencji identyfikujący żądanie logiczne.

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')

Przykład używa wyceny z kroku 5 i generuje klucz przez uuidgen. Przyjęcie zwraca HTTP 202 i identyfikator wykonania.

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

Odpowiedź zawiera też wersję cen, wynik, błędy i daty. chargedMicros: 0 podczas przetwarzania nie oznacza ostatecznie bezpłatnego wykonania.

7. Odpytuj ten sam identyfikator

Używaj ID z kroku 6 i odpytuj co najmniej co pięć sekund do zakończenia.

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 i waiting oznaczają trwające przetwarzanie. Przy succeeded odczytaj output i chargedMicros. Inne stany opisuje Wykonania i rozliczenia.

Jeśli odpowiedź jest nieznana, nie wysyłaj ponownie z nowym kluczem idempotencji. Ten sam korpus i klucz zwracają już przyjęte wykonanie.

Powiązane strony

Następnie przeczytaj odpowiednie strony:

Uwierzytelnianie żądań: uprawnienia i przechowywanie kluczy
Wykonania i rozliczenia: długie zadania, ponawianie i rozliczenia
Dokumentacja API: endpointy, stany i limity
Dokumentacja Developer Platform: aktualne przykłady

API

CLI

Serwer MCP

Pierwsze kroki

Przegląd

Wymagania

Uruchomienie API

1. Utwórz klucz w Developer Platform

2. Ustaw klucz i bazowy URL

3. Sprawdź projekt klucza

4. Sprawdź dostępne narzędzia

5. Pobierz wycenę przed wykonaniem

6. Wykonaj wycenione żądanie

7. Odpytuj ten sam identyfikator

Powiązane strony

​Przegląd

​Wymagania

​Uruchomienie API

​1. Utwórz klucz w Developer Platform

​2. Ustaw klucz i bazowy URL

​3. Sprawdź projekt klucza

​4. Sprawdź dostępne narzędzia

​5. Pobierz wycenę przed wykonaniem

​6. Wykonaj wycenione żądanie

​7. Odpytuj ten sam identyfikator

​Powiązane strony

Przegląd

Wymagania

Uruchomienie API

1. Utwórz klucz w Developer Platform

2. Ustaw klucz i bazowy URL

3. Sprawdź projekt klucza

4. Sprawdź dostępne narzędzia

5. Pobierz wycenę przed wykonaniem

6. Wykonaj wycenione żądanie

7. Odpytuj ten sam identyfikator

Powiązane strony