OpenAI Decisions API Tutorial: dein erster Decision-Call

Schritt 1 — Schlüssel holen

Öffne den Playground und drücke einmal Run — Gast-Session, API-Schlüssel und 1 kostenloser Credit werden automatisch erstellt. Für Produktion melde dich an und lege einen benannten Schlüssel im Dashboard unter API keys an. Schlüssel werden im Authorization-Bearer-Header gesendet.

Halte den Schlüssel serverseitig. Jeder Request mit ihm wird auf dein Guthaben gebucht — nie in Browser-Code oder ein öffentliches Repo legen.

Schritt 2 — den ersten Request senden

Ein Decision-Request hat drei Felder: model (decisions-1 oder decisions-latest), state (der Kontext, den das Modell liest — ein String, JSON-Objekt oder Text-Array) und questions (eine Map mit 1 bis 6 Frage-IDs). Schreibe die eigentliche Frage in instructions — die ID ist nur das Label, unter dem die Antwort zurückkommt.

Eine noul-Frage ist eine Ja/Nein-Entscheidung: Das Antwortfeld noul ist die Wahrscheinlichkeit, dass die Aussage wahr ist.

curl https://decisions-api.net/api/v1/decisions \
  -H "Authorization: Bearer $DECISIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "decisions-1",
  "state": "I was charged twice for my subscription this morning.",
  "questions": {
    "refund": {
      "type": "noul",
      "instructions": "Is the customer asking for money back?"
    }
  }
}'

Schritt 3 — eine choice-Frage hinzufügen

Eine choice-Frage wählt ein Label aus deiner Liste. criteria ist ein Objekt aus 2 bis 8 Options-IDs, jede mit kurzer Beschreibung — das Modell liest die Beschreibung, also schreibe sie wie eine Routing-Regel.

Eine score-Frage funktioniert genauso, nimmt aber ein geordnetes Array aus 2 bis 10 Stufenbeschreibungen, niedrigste zuerst. Alle drei Typen lassen sich in einem Call mischen — bis zu sechs Fragen.

{
  "team": {
    "type": "choice",
    "instructions": "Which team should own this ticket?",
    "criteria": {
      "payments": "Checkout, billing, or payment processing.",
      "frontend": "Rendering or browser behavior.",
      "account": "Login, permissions, or profile."
    }
  }
}

Schritt 4 — die Wahrscheinlichkeiten lesen

Eine erfolgreiche Response enthält model, answers nach deinen Frage-IDs, usage und credits_used. Eine noul-Antwort ist nur die Wahrscheinlichkeit. Eine choice-Antwort enthält den siegenden choice, eine Wahrscheinlichkeit pro Option und einen Konfidenzwert.

Der Zweitplatzierte zählt genauso wie der Sieger. Zwei Optionen bei jeweils etwa 0.5 ist etwas anderes als 0.9 zu 0.1 — behandle knappe Fälle als Review-Kandidaten, nicht als sichere Treffer.

{
  "model": "decisions-1",
  "answers": {
    "refund": { "type": "noul", "noul": 0.98 }
  },
  "credits_used": 1
}

Schritt 5 — Schwellenwert setzen und Fehler behandeln

Wähle einen Konfidenz-Schwellenwert aus deinem eigenen Traffic: darüber akzeptieren, den Rest an einen Menschen. Starte hoch (0,7–0,8) und senke ihn erst, nachdem du die Fälle darunter geprüft hast.

402 heißt Guthaben leer; 429 oder 502 heißt später wiederholen — fehlgeschlagene Calls werden nicht berechnet. 422 ist ein Body-Validierungsfehler, und die Meldung nennt das Feld.

const res = await fetch('https://decisions-api.net/api/v1/decisions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DECISIONS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})

if (res.status === 402) { /* out of credits */ }
if (res.status === 429 || res.status === 502) { /* retry later */ }

const { answers } = await res.json()
const team = answers.team

if (team.type === 'choice' && team.confidence >= 0.7) {
  routeTo(team.choice)          // confident: auto-assign
} else {
  queueForHuman(team)           // low confidence or near-tie: review
}

FAQ