Dokumentacja API Jev

Przegląd

Jev ewaluuje jeden state — ticket wsparcia, log czatu, wywołanie narzędzia, dowolny tekst lub JSON — wobec zestawu typowanych pytań i zwraca ustrukturyzowane odpowiedzi, na których Twój kod może rozgałęziać. Nie generuje tekstu.

Jedno żądanie może zadać do 8 pytań; są ewaluowane razem i dzielą koszt wejścia state. Treść żądania ma ten sam kształt, który akceptuje API SystemOne TypeSafe — żeby przenieść działającą integrację, podmień bazowy URL i klucz Bearer.

• POST https://jevmodel.org/v1/systemone — jedyny endpoint decyzyjny.
• CORS jest otwarty (access-control-allow-origin: *), endpoint odpowiada z każdego origin. I tak trzymaj klucz na serwerze.
• Playground wysyła identyczną treść żądania przez Twoją sesję przeglądarki — to, co tam podejrzysz, to to, co wysyłasz.

Uwierzytelnianie

Każde wywołanie API wymaga klucza jevmodel.org. Utwórz go w Dashboard → API keys; klucze zaczynają się od sk- i są pokazywane raz przy tworzeniu. Zapisz go jako zmienną środowiskową, np. JEVMODEL_API_KEY.

Authorization: Bearer $JEVMODEL_API_KEY

Klucze należą do salda tokenów Twojego konta i można je unieważnić w dashboardzie. Nigdy nie osadzaj klucza w kodzie po stronie klienta ani nie commituj go do repozytorium — po wycieku unieważnij i wygeneruj nowy. Playground uwierzytelnia Twoją zalogowaną sesję przeglądarki i nie potrzebuje klucza.

Endpoint HTTP

Wyślij treść JSON do endpointu ewaluacji z uwierzytelnianiem Bearer:

POST /v1/systemone HTTP/1.1
Host: jevmodel.org
Authorization: Bearer $JEVMODEL_API_KEY
Content-Type: application/json
Idempotency-Key: ticket-4821-run-1   # optional

Idempotency-Key jest opcjonalny (do 100 znaków). Ponowienia z tym samym kluczem używają oryginalnego rekordu rozliczenia, więc powtórzone żądanie nie może być naliczone dwukrotnie za to samo wejście.

curl -X POST https://jevmodel.org/v1/systemone \
  -H "Authorization: Bearer $JEVMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "The customer has been billed twice and wants a refund today.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Which queue should own this ticket?",
        "criteria": {
          "billing": "Payments, refunds, invoices",
          "technical": "Product errors and usage problems",
          "sales": "Pricing, upgrades, new business"
        }
      },
      "escalate": {
        "type": "noul",
        "instructions": "Does this need a human right now?"
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this for the customer?",
        "criteria": ["routine", "soon", "urgent", "critical"]
      }
    }
  }'

Treść żądania

Jeden obiekt JSON ze state i mapą pytań:

{
  "model": "jev-latest",
  "state": "The customer has been billed twice and wants a refund today.",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which queue should own this ticket?",
      "criteria": {
        "billing": "Payments, refunds, invoices",
        "technical": "Product errors and usage problems",
        "sales": "Pricing, upgrades, new business"
      }
    },
    "escalate": {
      "type": "noul",
      "instructions": "Does this need a human right now?"
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this for the customer?",
      "criteria": ["routine", "soon", "urgent", "critical"]
    }
  }
}

Każde pytanie potrzebuje type i instructions (do 1 800 znaków) mówiących modelowi, co rozstrzygnąć. criteria dostarcza przestrzeń odpowiedzi — wymagane dla choice i score, opcjonalne dla noul.

Typy pytań

Wybierz kształt odpowiedzi, na którym Twoja aplikacja może działać.

Serializowane criteria są ograniczone do 2 000 znaków na pytanie. Błędy walidacji zwracają 422, zanim zarezerwowane zostaną tokeny — błędne żądania nigdy nie są rozliczane.

JSON odpowiedzi

Odpowiedź 200 to samo wyjście modelu: rozwiązany model, jedna odpowiedź na nazwę pytania i usage. Poniższe wartości są ilustracyjne — uruchom żądanie dla realnego wyjścia.

{
  "model": "jev-latest",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.93, "technical": 0.05, "sales": 0.02 },
      "confidence": 0.93
    },
    "escalate": {
      "type": "noul",
      "noul": 0.12
    },
    "urgency": {
      "type": "score",
      "score": 1.4,
      "confidence": 0.88
    }
  },
  "usage": { "input_tokens": 136, "output_tokens": 18 }
}

• answers jest kluczowane Twoimi nazwami pytań — czytasz pola, o które pytałeś.
• Przy choice rozgałęziaj po wybranej etykiecie i sprawdzaj probabilities, gdy potrzebujesz pełnego rozkładu.
• noul to P(tak) — Twój kod ustawia próg działania.
• usage.input_tokens to faktyczne obciążenie tego wywołania; tokeny wyjściowe są darmowe.

Rozliczanie

API rozlicza tylko tokeny wejściowe — wyjście jest darmowe. Każde wywołanie najpierw rezerwuje szacunek, a potem rozlicza na faktyczne usage.input_tokens zgłoszone przez model. Jeśli Jev zawiedzie upstream, rezerwacja jest automatycznie w pełni zwracana.

• Zaloguj się raz i otrzymaj 100 000 darmowych tokenów wejściowych; płatne pakiety od $9,90 i nigdy nie wygasają.
• Za małe saldo zwraca 402 przed wywołaniem Jev.
• X-Tokens-Remaining na każdej odpowiedzi 200 to Twoje saldo po rozliczeniu.
• Oszacuj sam: ceil(JSON.stringify({state, questions}).length / 4).

Modele i limity

jev-latest to domyślny i aktualnie serwowany model — pole model jest opcjonalne. Warianty Laya pokazywane w playgroundzie są w drodze i nie są jeszcze wystawione przez ten endpoint.

Te liczby opisują walidator API; model upstream może mieć własne limity kontekstu.

Błędy i ponowienia

Błędy zwracają kopertę JSON z maszynowo czytelnym type i ludzkim message:

{
  "error": {
    "type": "invalid_request_error",
    "message": "At most 8 questions per request."
  }
}

Ponawiaj 429 i 502 z exponential backoff — okno rate limitu jest minutowe, krótkie pauzy zwykle wystarczą. Wysyłaj Idempotency-Key przy ponowieniach, by powtórzone żądanie rozliczyło się na ten sam rekord zamiast naliczyć podwójnie.

Serwer MCP dla agentów

jevmodel.org prowadzi też zdalny serwer MCP przez Streamable HTTP pod https://jevmodel.org/mcp. Udostępnia cztery narzędzia — jev_decide (pełny kontrakt state-plus-questions), jev_noul, jev_choice i jev_score — dzięki czemu agenty kodujące jak Claude Code, Cursor czy Cline wywołują Jev bez pisania HTTP.

claude mcp add --transport http jev https://jevmodel.org/mcp \
  --header "Authorization: Bearer $JEVMODEL_API_KEY"

• Ten sam klucz Authorization: Bearer sk-… i to samo saldo tokenów co to API — tools/call rozlicza tylko tokeny wejściowe.
• initialize, ping i tools/list są bez uwierzytelniania; tylko tools/call używa Twojego klucza.
• GET /mcp zwraca kartę discovery JSON dla agentów i ludzi.

Komendy instalacji dla Claude Code i Cursor oraz pasujący agent skill (podręcznik osądu) są na stronie narzędzia agenta.

Przewodnik po narzędziach agenta →

Z playgroundu do API

Najpierw zbuduj scenariusz w playgroundzie — podgląd żądania pokazuje dokładną treść JSON, którą Twoja aplikacja powinna wysłać, a Copy API example daje odpowiednie cURL. Gdy odpowiedzi pasują, utwórz klucz w dashboardzie i zamień sesję przeglądarki na uwierzytelnianie Bearer.

Więcej: Jak używać Jev przeprowadza pierwsze wywołanie od początku do końca, a Przykłady API Jev mają wzorce produkcyjne dla każdego typu pytania.