Überblick
Jev evaluiert einen State — ein Support-Ticket, ein Chat-Log, einen Tool-Aufruf, beliebigen Text oder JSON — gegen typisierte Fragen und liefert strukturierte Antworten, auf die dein Code verzweigen kann. Es generiert keinen Text.
Ein Request kann bis zu 8 Fragen stellen; sie werden gemeinsam evaluiert und teilen die State-Inputkosten. Der Request Body hat dieselbe Form wie die TypeSafe-SystemOne-API — eine funktionierende Integration migrierst du durch Austausch von Basis-URL und Bearer-Key.
- POST
https://jevmodel.org/v1/systemone— der einzige Entscheidungs-Endpoint. - CORS ist offen (
access-control-allow-origin: *), der Endpoint antwortet von jedem Origin. Halte deinen Key trotzdem auf dem Server. - Der Playground sendet dieselbe Request-Form über deine Browser-Session — was du dort siehst, ist, was du sendest.
Authentifizierung
Jeder API-Aufruf braucht einen jevmodel.org API-Key. Erstelle einen unter Dashboard → API keys; Keys beginnen mit sk- und werden nur einmal bei der Erstellung gezeigt. Speichere ihn als Umgebungsvariable, z. B. JEVMODEL_API_KEY.
Authorization: Bearer $JEVMODEL_API_KEY Keys gehören zum Token-Guthaben deines Kontos und können im Dashboard widerrufen werden. Gib einen Key nie in Client-Code aus und committe ihn nicht in ein Repository — bei einem Leck widerrufe ihn und stelle einen neuen aus. Der Playground authentifiziert über deine angemeldete Browser-Session und braucht keinen Key.
HTTP-Endpoint
Sende einen JSON-Body mit Bearer-Authentifizierung an den Evaluierungs-Endpoint:
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 ist optional (bis zu 100 Zeichen). Retries mit demselben Key nutzen den ursprünglichen Abrechnungsdatensatz — eine Wiederholung wird nicht doppelt für denselben Input berechnet.
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"]
}
}
}' Request Body
Ein JSON-Objekt mit einem State und einer Map von Fragen:
{
"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"]
}
}
} | Feld | Typ | Hinweise |
|---|---|---|
model | string | Optional; Standard ist jev-latest. |
state | string, object oder array | Pflicht. Serialisierte Form maximal 1.000.000 Zeichen. |
questions | object | Pflicht-Map von 1–8 Fragennamen auf typisierte Definitionen. Namen sind Identifier: Buchstaben, Ziffern und _, max. 64 Zeichen. |
assets | object | Optional (experimentell). Bis zu 4 PNG/JPEG-Bilder, jeweils unter einem Referenznamen, den Sie in state, instructions oder criteria nennen. Siehe Bilder & Box. |
Jede Frage braucht ein type und instructions (bis zu 1.800 Zeichen), die dem Modell sagen, was es entscheiden soll. criteria liefert den Antwortraum — Pflicht für Choice und Score, optional für Noul.
Fragetypen
Wähle die Antwortform, mit der deine Anwendung arbeiten kann.
| Typ | Criteria | Antwort |
|---|---|---|
noul | Optionale true / false-Label-Beschreibungen. | noul — die Wahrscheinlichkeit für Ja, 0 bis 1. |
choice | Objekt mit 2–20 Options-Keys und Beschreibungen. | Gewählte choice, eine probabilities-Map und confidence. |
score | Geordnetes Array von 2–10 Stufen. | Numerischer score (kann gebrochen sein) und confidence. |
box | Nicht verwendet — nur instructions. | box mit normierten Kanten (top/bottom/left/right, 0–1) und confidence. Experimentell; erfordert jev-preview. |
Serialisierte criteria sind auf 2.000 Zeichen pro Frage begrenzt. Validierungsfehler liefern 422, bevor Tokens reserviert werden — fehlerhafte Requests werden nie berechnet.
Bilder und Box (experimentell)
Jev 1.14 akzeptiert PNG- und JPEG-Bilder als Entscheidungsgrundlage — Bildverstehen, nicht Bildgenerierung. Legen Sie jedes Bild in assets unter einem Referenznamen ab und nennen Sie diese Referenz in state, in den instructions einer Frage oder in criteria; die Referenz wird an dieser Stelle zum Bild aufgelöst. Bild- und Box-Anfragen brauchen das Preview-Modell — setzen Sie model auf jev-preview.
{
"model": "jev-preview",
"state": "Shipment photo attached as img-1.",
"assets": {
"img-1": { "type": "image", "format": "jpg", "data_base64": "/9j/4AAQSkZJRg…" }
},
"questions": {
"damage_visible": {
"type": "noul",
"instructions": "Is there visible damage to the package in img-1?"
},
"damage_region": {
"type": "box",
"instructions": "Locate the damaged area in img-1"
}
}
} assetsbildet eine Referenz auf{ "type": "image", "format": "png|jpg", "data_base64": "…" }ab — maximal 4 Bilder, ~4 MB pro Bild nach der Kodierung.- Jedes Asset muss referenziert werden, und jede Verwendung kostet — Bilder zählen wie Text zu
usage.input_tokens. boxnimmt nurinstructionsund liefert immer eine Box — kombinieren Sie es mit einer Noul-Frage wie „ist X sichtbar“, wenn das Ziel fehlen kann.- Experimentelle Opt-in-Fläche: Der Proxy setzt den Upstream-Header automatisch, wenn die Anfrage Assets oder eine Box-Frage enthält. Multipart-Uploads werden nicht unterstützt — senden Sie base64.
Audio und Video werden weiterhin nicht unterstützt — wandeln Sie sie zuerst in Text oder strukturierte Daten um.
Response-JSON
Eine 200-Antwort ist die Modellausgabe selbst: das aufgelöste Modell, eine Antwort pro Fragename und Usage. Die Werte unten sind illustrativ — echte Ausgaben erhältst du im Request.
{
"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 }
} answersist nach deinen Fragennamen gekeyed — du liest die Felder, die du gefragt hast.- Bei
choiceverzweigst du auf dem gewählten Label und prüfstprobabilitiesfür die volle Verteilung. noulist P(ja) — dein Code legt den Schwellenwert fest.usage.input_tokensist, was dieser Aufruf tatsächlich berechnet hat; Output-Tokens sind kostenlos.
Abrechnung
Die API rechnet nur Input-Tokens ab — Output ist kostenlos. Jeder Aufruf wird mit den tatsächlichen usage.input_tokens abgerechnet, die das Modell meldet. Bei Gratis-Tokens wird vorab eine Schätzung reserviert und danach auf diesen Wert abgerechnet. Scheitert Jev upstream, wird nichts berechnet.
- Einmal anmelden und 100.000 Input-Tokens gratis erhalten; bezahlte Packs ab $9,90, laufen nie ab.
- Zu wenig Guthaben liefert
402, bevor Jev aufgerufen wird. X-Tokens-Remainingauf jeder 200-Antwort ist dein Guthaben nach Verrechnung.- Selbst schätzen:
Σ ceil((state + question).length / 4)– der State zählt einmal pro Frage.
Modelle und Limits
jev-latest ist der Standard und das aktuell ausgelieferte Modell — das model-Feld ist optional. Die im Playground gezeigten Laya-Varianten sind geplant und über diesen Endpoint noch nicht verfügbar.
| Limit | Wert |
|---|---|
| Fragen pro Request | 8 |
| Fragename | Identifier ≤ 64 Zeichen |
Serialisierter state | 1.000.000 Zeichen |
instructions pro Frage | 1.800 Zeichen |
| Choice-Optionen / Score-Stufen | 2–20 Optionen, 2–10 Stufen |
Serialisierte criteria | 2.000 Zeichen pro Frage |
| Rate Limit | 120 Requests / Minute pro Key |
Bilder pro Anfrage (assets) | 4 |
| Bildformat / -größe | PNG oder JPEG base64, ≤ ~4 MB pro Bild |
| Bildabmessungen | 256–1.568 px pro Seite |
Diese Werte beschreiben den API-Validator; das Upstream-Modell kann eigene Kontextlimits haben.
Fehler und Retries
Fehler liefern einen JSON-Umschlag mit maschinenlesbarem type und menschlicher message:
{
"error": {
"type": "invalid_request_error",
"message": "At most 8 questions per request."
}
} | Status | Typ | Ursache | Berechnet? |
|---|---|---|---|
401 | authentication_error | Fehlender, ungültiger oder widerrufener Key. | Nein |
402 | insufficient_credits | Geschätzte Input-Tokens übersteigen das Guthaben. | Nein |
422 | invalid_request_error | Body besteht die Validierung nicht — siehe message. | Nein |
429 | rate_limit_error | Mehr als 120 Requests in dieser Minute. | Nein |
502 | upstream_error | Jev konnte den Aufruf nicht abschließen. | Nein — erstattet |
429 und 502 mit exponentiellem Backoff wiederholen — das Rate-Fenster ist pro Minute, kurze Pausen reichen meist. Sende beim Retry einen Idempotency-Key, damit ein wiederholter Request auf denselben Abrechnungsdatensatz bucht statt doppelt zu berechnen.
MCP-Server für Agents
jevmodel.org betreibt außerdem einen Remote-MCP-Server über Streamable HTTP unter https://jevmodel.org/mcp. Er stellt vier Tools bereit — jev_decide (der volle State-plus-Questions-Vertrag), jev_noul, jev_choice und jev_score — damit Coding-Agents wie Claude Code, Cursor oder Cline Jev ohne HTTP-Code aufrufen können.
claude mcp add --transport http jev https://jevmodel.org/mcp \
--header "Authorization: Bearer $JEVMODEL_API_KEY" - Gleicher
Authorization: Bearer sk-…-Key und dasselbe Token-Guthaben wie diese API —tools/callberechnet nur Input-Tokens. initialize,pingundtools/listsind unauthentifiziert; nurtools/callnutzt deinen Key.GET /mcpliefert eine JSON-Discovery-Karte für Agents und Menschen.
Setup-Befehle für Claude Code und Cursor sowie das passende Agent-Skill (Urteils-Playbook) findest du auf der Agent-Tools-Seite.
Vom Playground zur API
Baue das Szenario zuerst im Playground — die Request-Vorschau zeigt den exakten JSON-Body, den deine Anwendung senden soll, und Copy API example liefert das passende cURL. Wenn die Antworten passen, erstelle einen Key im Dashboard und tausche die Browser-Session gegen Bearer-Authentifizierung.
Weiterlesen: Wie man Jev nutzt führt einen ersten Aufruf komplett durch, und Jev API-Beispiele enthält Produktionsmuster für jeden Fragetyp.