Skip to Content
APIOpenAI-kompatibles ProtokollResponses (Empfohlen)

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 Cachinginstructions und input sind 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/responses

Anfrageparameter

ParameterTypErforderlichBeschreibung
modelstringModellkennung, z.B. openai/gpt-5.4-mini
inputstring | arrayEingabeinhalt, entweder als reine Textzeichenkette oder als strukturiertes Nachrichtenarray
instructionsstringSystemanweisungen (unabhängig vom Input, profitieren automatisch vom Prompt Caching)
streambooleanSSE-Streaming-Antwort aktivieren, Standard false
max_output_tokensnumberMaximale Anzahl generierter Tokens
temperaturenumberSampling-Temperatur 0-2, Standard 1
top_pnumberNucleus-Sampling-Parameter
toolsarrayVerfügbare Tool-Definitionen (Function Calling)
tool_choicestring | objectTool-Auswahlstrategie: auto, none oder ein bestimmtes Tool
truncationstringKürzungsstrategie: auto automatisch kürzen / disabled Fehler bei Überschreitung (Standard)
textobjectKonfiguration des Textgenerierungsformats
storebooleanAntwort speichern (Standard true)
metadataobjectBenutzerdefinierte Metadaten als Schlüssel-Wert-Paare
providerobjectOfoxAI-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 Assistenten

Wenn 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

Terminal
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

FeldTypBeschreibung
idstringEindeutige Kennung der Antwort, beginnt mit resp_
objectstringFester Wert "response"
created_atnumberErstellungszeitstempel (Unix-Sekunden)
modelstringTatsächlich verwendete Modell-ID
statusstringAntwortstatus: completed, failed, in_progress, cancelled
outputarrayArray von Ausgabe-Items, enthält Nachrichten und Tool-Aufrufe
usageobjectToken-Verbrauchsstatistik

Strukturierte Nachrichteneingabe

Verwenden Sie ein strukturiertes Nachrichtenarray, um mehrstufige Dialoge umzusetzen:

multi_turn.py
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:

stream.py
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-TypBeschreibung
response.createdAntwortobjekt erstellt
response.output_item.addedNeues Ausgabe-Item hinzugefügt
response.content_part.addedNeues Inhaltsfragment hinzugefügt
response.output_text.deltaText-Inkrement (token-weise Ausgabe)
response.output_item.doneAusgabe-Item abgeschlossen
response.completedAntwort vollständig abgeschlossen
response.function_call_arguments.deltaInkrement der Function-Call-Argumente
response.function_call_arguments.doneFunction-Call-Argumente abgeschlossen

Function Calling

Die Responses API unterstützt Tool-Aufrufe nativ:

tools.py
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

WertBeschreibung
"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

MerkmalChat CompletionsResponses API
Endpunkt/v1/chat/completions/v1/responses
Eingabeformatmessages-Arrayinput-Zeichenkette oder strukturiertes Item-Array
Systemanweisungenrole: "system"-Nachrichtinstructions-Parameter (unabhängig gecacht)
Prompt CachingSystemanweisungen in messages vermischt, Cache-Präfix instabilinstructions wird unabhängig übergeben, automatisch gecacht, höhere Trefferquote
Ausgabeformatchoices[0].message.contentoutput[0].content[0].text oder output_text
Tool-Aufrufetool_calls innerhalb der messageEigenes function_call-Output-Item
Tool-Ergebnisserole: "tool"-Nachrichtfunction_call_output-Input-Item
Streaming-Eventschat.completion.chunkStrukturierte Event-Typen (response.*)
Token-Felderprompt_tokens / completion_tokensinput_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.

Last updated on