Wenn deine Anwendung die Antwort des Modells weiterverarbeitet, brauchst du sauberes JSON statt Fließtext. Dafür gibt es das Feld response_format. Es kennt zwei Stufen: Mit json_object bekommst du gültiges JSON in beliebiger Form, mit json_schema gibst du die Struktur genau vor.
Die drei Varianten
| Wert | Ergebnis |
|---|---|
{"type": "text"} |
normaler Text, das ist auch der Standard |
{"type": "json_object"} |
gültiges JSON, die Struktur bestimmt das Modell |
{"type": "json_schema", "json_schema": {…}} |
JSON nach deinem Schema |
Beliebiges JSON mit json_object
{
"model": "groq/openai/gpt-oss-120b",
"messages": [
{"role": "system", "content": "Antworte als JSON mit den Feldern betreff und prioritaet."},
{"role": "user", "content": "Kunde schreibt: Unser Login geht seit heute Morgen nicht mehr."}
],
"response_format": {"type": "json_object"}
}
Beschreibe im Prompt trotzdem, welche Felder du erwartest. json_object sorgt nur dafür, dass gültiges JSON herauskommt, nicht für bestimmte Felder. Manche Anbieter verlangen, dass das Wort „JSON“ im Prompt vorkommt. Fehlt es in allen Nachrichten, ergänzen wir automatisch einen kurzen Hinweis.
Eine feste Struktur mit json_schema
{
"model": "groq/openai/gpt-oss-120b",
"messages": [{"role": "user", "content": "Kunde schreibt: Unser Login geht seit heute Morgen nicht mehr."}],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "ticket",
"strict": true,
"schema": {
"type": "object",
"properties": {
"betreff": {"type": "string"},
"prioritaet": {"type": "string", "enum": ["niedrig", "mittel", "hoch"]}
},
"required": ["betreff", "prioritaet"],
"additionalProperties": false
}
}
}
}
Die Antwort steht wie immer in choices[0].message.content, als Text mit dem JSON darin. Parse sie in deinem Code.
Lässt du strict weg, gilt false. Mit strict: true hält sich das Modell genauer an das Schema, dafür stellen manche Anbieter strengere Anforderungen an das Schema selbst. Lehnt der Anbieter dein Schema ab, kommt 400 invalid_field_value mit param response_format.
Welche Modelle das können
Nicht jedes Modell beherrscht beide Varianten. In GET /v1/models steht bei jedem Modell unter capabilities, ob json_object und json_schema auf true stehen. Wählst du ein Modell ohne die Fähigkeit, antwortet die API mit 400 unsupported_for_model, statt dir heimlich Fließtext zu liefern. So merkst du den Fehler sofort und nicht erst beim Parsen. Wie du die Fähigkeiten liest, steht in Was ein Modell kann: Fähigkeiten, Grenzen, Ausgabelänge und Denktiefe prüfen.
Auf dem Endpunkt /responses
Bei /responses kannst du dasselbe Feld response_format verwenden. Alternativ nimmt der Endpunkt die Schreibweise der OpenAI-Bibliotheken an, text.format, bei der das Schema flach im Objekt steht:
"text": {
"format": {"type": "json_schema", "name": "ticket", "strict": true, "schema": { … }}
}
Schick nur eine der beiden Schreibweisen. Beide zusammen lehnt die API mit HTTP 400 ab, ebenso weitere Felder in text wie verbosity. In der Antwort steht das gewählte Format unter text.format.
Wenn etwas nicht klappt
400 unsupported_for_model: Das Modell kann diese Variante nicht. Nimm ein anderes Modell oder weiche aufjson_objectaus.400 invalid_field_valuebeiresponse_format: Prüfe dein Schema. Häufige Ursachen sind fehlenderequired-Angaben oder Typen, die der Anbieter im strikten Modus nicht unterstützt.- Antwort ist abgeschnitten und kein gültiges JSON: Meist hat das Modell die Ausgabegrenze erreicht. Erhöhe
max_tokensoder verkleinere die erwartete Antwort.