Responses API (Empfohlen)
Erstellen Sie Modellantworten. Unterstützt Text- und Bildeingaben, generiert Text- oder JSON-Ausgaben. Unterstützt Function Calling, Streaming-Antworten und mehrstufige Dialoge.
Für neue Projekte wird die Responses API empfohlen. Dies ist die neue Generation der OpenAI API und bietet gegenüber Chat Completions folgende Vorteile:
- Natives Prompt Caching —
instructionsundinputsind getrennt; Systemanweisungen dienen automatisch als Cache-Präfix. In mehrstufigen Dialogen erzielt der unveränderte Präfixteil eine höhere Cache-Trefferquote, was bis zu 50 % der Eingabe-Token-Kosten einsparen und gleichzeitig die Latenz reduzieren kann. - Strukturiertes Item-Modell — Ein- und Ausgabeformate sind klarer, mit nativer Unterstützung für Tool-Call-Abläufe.
- Reichhaltigere Streaming-Events — Feingranulare SSE-Event-Typen erleichtern das Echtzeit-UI-Rendering.
Endpunkt
POST https://api.ofox.ai/v1/responsesAnfrageparameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
model | string | ✅ | Modellkennung, z.B. openai/gpt-5.4-mini |
input | string | array | ✅ | Eingabeinhalt, entweder als reine Textzeichenkette oder als strukturiertes Nachrichtenarray |
instructions | string | — | Systemanweisungen (unabhängig vom Input, profitieren automatisch vom Prompt Caching) |
stream | boolean | — | SSE-Streaming-Antwort aktivieren, Standard false |
max_output_tokens | number | — | Maximale Anzahl generierter Tokens |
temperature | number | — | Sampling-Temperatur 0-2, Standard 1 |
top_p | number | — | Nucleus-Sampling-Parameter |
tools | array | — | Verfügbare Tool-Definitionen (Function Calling) |
tool_choice | string | object | — | Tool-Auswahlstrategie: auto, none oder ein bestimmtes Tool |
truncation | string | — | Kürzungsstrategie: auto automatisch kürzen / disabled Fehler bei Überschreitung (Standard) |
text | object | — | Konfiguration des Textgenerierungsformats |
store | boolean | — | Antwort speichern (Standard true) |
metadata | object | — | Benutzerdefinierte Metadaten als Schlüssel-Wert-Paare |
provider | object | — | OfoxAI-Erweiterung: Routing- und Failover-Konfiguration |
Input-Format
input unterstützt zwei Formate:
1. Einfache Zeichenkette — direkt Text übergeben
{
"input": "Hallo, stelle dich bitte vor"
}2. Strukturiertes Nachrichtenarray — mehrstufige Dialoge und multimodale Eingaben
interface InputItem {
type: 'message'
role: 'user' | 'assistant'
content: ContentPart[]
id?: string // Bei Assistant-Nachrichten erforderlich
status?: 'completed' // Bei Assistant-Nachrichten erforderlich
}
type ContentPart =
| { type: 'input_text'; text: string } // Texteingabe des Nutzers
| { type: 'input_image'; image_url: string } // Bildeingabe
| { type: 'output_text'; text: string; annotations?: any[] } // Textausgabe des AssistentenWenn in einem mehrstufigen Dialog assistant-Nachrichten enthalten sind, sind die Felder id und status erforderlich.
Die Responses API ist zustandslos konzipiert; jede Anfrage muss den vollständigen Gesprächsverlauf mitsenden.
Anfragebeispiele
cURL
curl https://api.ofox.ai/v1/responses \
-H "Authorization: Bearer $OFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.4-mini",
"input": "Erkläre, was ein API Gateway ist",
"instructions": "Du bist ein hilfreicher technischer Assistent und antwortest auf Deutsch.",
"max_output_tokens": 1024
}'Antwortformat
{
"id": "resp_abc123",
"object": "response",
"created_at": 1703123456,
"model": "openai/gpt-5.4-mini",
"status": "completed",
"output": [
{
"type": "message",
"id": "msg_def456",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Ein API Gateway ist ein...",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 25,
"output_tokens": 150,
"total_tokens": 175
}
}Beschreibung der Antwortfelder
| Feld | Typ | Beschreibung |
|---|---|---|
id | string | Eindeutige Kennung der Antwort, beginnt mit resp_ |
object | string | Fester Wert "response" |
created_at | number | Erstellungszeitstempel (Unix-Sekunden) |
model | string | Tatsächlich verwendete Modell-ID |
status | string | Antwortstatus: completed, failed, in_progress, cancelled |
output | array | Array von Ausgabe-Items, enthält Nachrichten und Tool-Aufrufe |
usage | object | Token-Verbrauchsstatistik |
Strukturierte Nachrichteneingabe
Verwenden Sie ein strukturiertes Nachrichtenarray, um mehrstufige Dialoge umzusetzen:
Python
response = client.responses.create(
model="openai/gpt-5.4-mini",
input=[
{
"type": "message",
"role": "user",
"content": [
{"type": "input_text", "text": "Was ist die Hauptstadt Frankreichs?"}
]
},
{
"type": "message",
"role": "assistant",
"id": "msg_abc123",
"status": "completed",
"content": [
{"type": "output_text", "text": "Die Hauptstadt Frankreichs ist Paris.", "annotations": []}
]
},
{
"type": "message",
"role": "user",
"content": [
{"type": "input_text", "text": "Wie viele Einwohner hat sie?"}
]
}
]
)
print(response.output_text)Streaming-Antwort
Setzen Sie stream: true, um eine SSE-Streaming-Antwort zu aktivieren:
Python
stream = client.responses.create(
model="openai/gpt-5.4-mini",
input="Erzähle einen Witz übers Programmieren",
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)Streaming-Event-Typen
Die Streaming-Antwort sendet folgende Events über SSE:
data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}}
data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"in_progress","content":[]}}
data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Hal"}
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"lo"}
data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Hallo..."}]}}
data: {"type":"response.completed","response":{"id":"resp_abc123","object":"response","status":"completed","usage":{"input_tokens":12,"output_tokens":45,"total_tokens":57}}}
data: [DONE]| Event-Typ | Beschreibung |
|---|---|
response.created | Antwortobjekt erstellt |
response.output_item.added | Neues Ausgabe-Item hinzugefügt |
response.content_part.added | Neues Inhaltsfragment hinzugefügt |
response.output_text.delta | Text-Inkrement (token-weise Ausgabe) |
response.output_item.done | Ausgabe-Item abgeschlossen |
response.completed | Antwort vollständig abgeschlossen |
response.function_call_arguments.delta | Inkrement der Function-Call-Argumente |
response.function_call_arguments.done | Function-Call-Argumente abgeschlossen |
Function Calling
Die Responses API unterstützt Tool-Aufrufe nativ:
Python
response = client.responses.create(
model="openai/gpt-5.4-mini",
input="Wie ist das Wetter heute in Berlin?",
tools=[
{
"type": "function",
"name": "get_weather",
"description": "Aktuelles Wetter für eine bestimmte Stadt abrufen",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Name der Stadt, z.B. Berlin"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
}
],
tool_choice="auto"
)
# Tool-Aufrufe verarbeiten
for item in response.output:
if item.type == "function_call":
print(f"Funktion aufgerufen: {item.name}")
print(f"Argumente: {item.arguments}")Antwortformat bei Tool-Aufrufen
Wenn das Modell ein Tool aufruft, enthält output ein Item vom Typ function_call:
{
"id": "resp_abc123",
"object": "response",
"status": "completed",
"output": [
{
"type": "function_call",
"id": "fc_abc123",
"call_id": "call_xyz789",
"name": "get_weather",
"arguments": "{\"location\":\"Berlin\",\"unit\":\"celsius\"}"
}
],
"usage": {
"input_tokens": 45,
"output_tokens": 25,
"total_tokens": 70
}
}Tool-Ergebnisse übermitteln
Geben Sie das Ergebnis der Tool-Ausführung an das Modell zurück, indem Sie die vollständige Aufrufkette in input einfügen:
# Zweite Anfrage: Tool-Ergebnis übermitteln
response = client.responses.create(
model="openai/gpt-5.4-mini",
input=[
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "Wie ist das Wetter heute in Berlin?"}]
},
{
"type": "function_call",
"id": "fc_abc123",
"call_id": "call_xyz789",
"name": "get_weather",
"arguments": "{\"location\":\"Berlin\",\"unit\":\"celsius\"}"
},
{
"type": "function_call_output",
"id": "fco_abc123",
"call_id": "call_xyz789",
"output": "{\"temperature\":\"22°C\",\"condition\":\"sonnig\"}"
}
]
)
print(response.output_text)
# => "In Berlin ist es heute sonnig bei 22 °C – ideal für Aktivitäten im Freien."Tool-Choice-Optionen
| Wert | Beschreibung |
|---|---|
"auto" | Das Modell entscheidet selbst, ob es ein Tool aufruft (Standard) |
"none" | Tool-Aufrufe verboten |
{"type": "function", "name": "tool_name"} | Aufruf eines bestimmten Tools erzwingen |
Vergleich mit Chat Completions
| Merkmal | Chat Completions | Responses API |
|---|---|---|
| Endpunkt | /v1/chat/completions | /v1/responses |
| Eingabeformat | messages-Array | input-Zeichenkette oder strukturiertes Item-Array |
| Systemanweisungen | role: "system"-Nachricht | instructions-Parameter (unabhängig gecacht) |
| Prompt Caching | Systemanweisungen in messages vermischt, Cache-Präfix instabil | instructions wird unabhängig übergeben, automatisch gecacht, höhere Trefferquote |
| Ausgabeformat | choices[0].message.content | output[0].content[0].text oder output_text |
| Tool-Aufrufe | tool_calls innerhalb der message | Eigenes function_call-Output-Item |
| Tool-Ergebnisse | role: "tool"-Nachricht | function_call_output-Input-Item |
| Streaming-Events | chat.completion.chunk | Strukturierte Event-Typen (response.*) |
| Token-Felder | prompt_tokens / completion_tokens | input_tokens / output_tokens |
Beide APIs sind produktionsreif. Wenn Sie bereits eine Chat-Completions-Integration haben, ist keine Migration erforderlich. Für neue Projekte wird die Responses API empfohlen, insbesondere für Szenarien mit komplexen Tool-Call-Abläufen oder hoher Aufruffrequenz (Caching kann hier voll ausgenutzt werden, um Kosten zu senken). Siehe Function Calling-Anleitung.