Manche Anfragen dauern lange, etwa wenn ein Modell gründlich nachdenkt oder einen langen Text schreibt. Statt die Verbindung die ganze Zeit offen zu halten, startest du sie über den Endpunkt /responses als Hintergrundauftrag. Du bekommst sofort eine ID zurück und holst das Ergebnis ab, sobald es fertig ist, per Abfrage, per Stream oder per Webhook.
Der Endpunkt /responses
POST /v1/responses ist die Alternative zu Chat Completions im Format der Responses-API von OpenAI. Statt messages schickst du input, entweder als einfachen Text oder als Liste von Nachrichten. Den Antworttext findest du in output[].content[] mit type: "output_text", die OpenAI-Bibliotheken bieten dafür direkt output_text an.
Ohne weitere Angabe antwortet der Endpunkt synchron, wie Chat Completions. Mit stream: true kommen die Ereignisse als Stream. Mit background: true läuft der Auftrag im Hintergrund.
Einen Hintergrundauftrag starten
curl https://api.flowmodels.one/v1/responses \
-H "Authorization: Bearer at_dein_schluessel" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: angebot-2026-117-entwurf" \
-d '{"model": "groq/openai/gpt-oss-120b", "background": true, "input": "Schreibe einen ausführlichen Angebotstext für eine Website mit Online-Shop."}'
Die API antwortet sofort mit HTTP 202 und einem Objekt mit status: "queued":
{"id": "resp_018f1234-5678-7abc-9def-0123456789ab", "object": "response", "status": "queued", "store": true, "output": [], "output_text": ""}
Hintergrundaufträge werden immer gespeichert. background: true zusammen mit store: false lehnt die API ab.
Den Status abfragen
Mit GET /v1/responses/{id} fragst du den Stand ab. status durchläuft diese Werte:
queued: wartet auf die Verarbeitungin_progress: läuft geradecompleted: fertig, das Ergebnis steht inoutputfailed: fehlgeschlagen, Details inerrorcancelled: abgebrochenincomplete: vorzeitig beendet, zum Beispiel weil die Ausgabegrenze erreicht war
Frag in sinnvollen Abständen ab, etwa alle paar Sekunden. Jede Abfrage zählt zu deinem Anfragelimit.
Den Verlauf als Stream verfolgen und fortsetzen
Kombinierst du background: true mit stream: true, bekommst du die Ereignisse sofort als Stream, und der Auftrag läuft trotzdem bei uns. Jedes Ereignis trägt eine fortlaufende sequence_number. Merk dir die letzte, die du empfangen hast.
Reißt die Verbindung ab, läuft der Auftrag einfach weiter. Du setzt den Stream an der letzten Stelle fort:
curl -N "https://api.flowmodels.one/v1/responses/resp_018f1234-5678-7abc-9def-0123456789ab?stream=true&starting_after=41" \
-H "Authorization: Bearer at_dein_schluessel" \
-H "Accept: text/event-stream"
Du bekommst dann nur die Ereignisse nach Nummer 41. Dieser Abruf startet keinen neuen Modellaufruf und kostet nichts extra. starting_after ist eine ganze Zahl ab 0 und funktioniert nur zusammen mit stream=true.
Ergebnis per Webhook statt Abfrage
Statt regelmäßig nachzufragen, kann dein Server benachrichtigt werden. Lege dazu einen Webhook mit den Ereignissen response.completed, response.failed, response.cancelled und response.incomplete an, siehe Webhooks von FlowModels einrichten. Schick dessen UUID beim Start als webhook_endpoint_id mit. Die Zustellung enthält nur ID und Status, das Ergebnis holst du dann mit GET /responses/{id}. Wie du die Zustellung absicherst, steht in Webhook-Signatur prüfen.
Abbrechen
POST /v1/responses/{id}/cancel bricht einen laufenden Auftrag ab und liefert seinen aktuellen Zustand. Ist der Auftrag schon fertig, fehlgeschlagen oder abgebrochen, ist der Aufruf trotzdem erfolgreich und ändert nichts. Du kannst ihn also gefahrlos mehrfach senden. Bereits entstandene Kosten bleiben bestehen.
Wie lange das Ergebnis abrufbar ist
Gespeicherte Antworten und ihre Ereignisse kannst du 24 Stunden nach Abschluss abrufen. Danach, bei nicht gespeicherten Antworten und bei Antworten eines anderen Teams kommt 404 response_not_found. Hol dein Ergebnis also zeitnah ab und speichere es bei dir.
Gut zu wissen
- Mit
metadatakannst du bis zu 16 eigene Wertepaare mitgeben, etwa deine Auftragsnummer. Sie kommen mit der gespeicherten Antwort zurück. Bei Chat Completions ist das Feld nicht erlaubt. - Das Brain funktioniert hier genauso wie bei Chat Completions, mit
external_identifierundconversation, siehe Brain nutzen: Unterhaltungen je Endnutzer speichern und fortsetzen. - Die gespeicherte Antwort ist nicht dasselbe wie der Gesprächsverlauf im Brain. Nach 24 Stunden verschwindet nur die abrufbare Antwort, nicht die Unterhaltung.
- In der Python-Bibliothek schickst du eigene Felder wie
external_identifieroderwebhook_endpoint_idüberextra_body, siehe Die OpenAI-Bibliothek für Python und Node.js mit FlowModels nutzen.