🚀 Jetzt neu: FlowAI! Ein revolutionärer Chat mit personalisierten AI-Agenten. 🌟

FlowAI Routing API - Modelle gezielt auswählen

Nutze freigegebene Anbietermodelle mit eigener Euro-Abrechnung. Verwalte den Verlauf selbst oder ergänze mit einer Endnutzerkennung Brain, Dateien und Erinnerungen. Antworten sind synchron, als Stream und im Hintergrund verfügbar.

🚀 Schnellstart

Basis-URL: https://creativeskyline.de/api/flowai/v1
Ohne Abonnement, nach Verbrauch
Für FlowAI Routing ist kein FlowSuite-Abonnement erforderlich. Du zahlst nach Verbrauch und benötigen Guthaben oder einen freigeschalteten Kreditrahmen. Erstelle im FlowAI-API-Modul einen Schlüssel mit der Berechtigung „KI nutzen“ (kind: inference). „Schlüssel verwalten“ erlaubt nur die Verwaltung von API-Schlüsseln. Halte geheime Schlüssel in deinem eigenen Backend.

Die passende Schnittstelle

Diese Anleitung beschreibt das eigenständige Routing-Produkt. Die Produktwahl ist fest im API-Schlüssel hinterlegt; external_identifier aktiviert optional Brain-Kontext und wechselt nicht das Abrechnungsprodukt. Die Referenz für den FlowSuite-Abozugang beschreibt die abonnementgebundenen Modell-Aliase. Deren Pro-Voraussetzung gilt nicht für Routing; die Routing-Endpunkte findest du auf dieser Seite. Beide Nutzungsarten verwenden dieselbe Basis-URL.

Erste Anfrage vorbereiten

  1. Öffne im Modulwechsler FlowAI API und erstelle dort einen Schlüssel mit „KI nutzen“. Team-Inhaber haben Zugriff; andere Mitglieder benötigen die eigene FlowAI-API-Freigabe. Bei der API-basierten Schlüsselerstellung muss kind: inference ausdrücklich gesetzt werden; ohne Angabe entsteht ein Schlüssel mit „Schlüssel verwalten“ (kind: management).
  2. Lade im Prepaid-Modus mindestens 20 € Guthaben auf oder verwende eine ausdrücklich freigegebene Postpaid-Kreditlinie.
  3. Frage GET /models ab und wähle eine vollständige Modellkennung.
  4. Sende model und deine Nachrichten, optional ergänzt um external_identifier, über einen der beiden folgenden Endpunkte für KI-Anfragen.
  5. Wenn du Brain verwendest, speichere conversation aus der Antwort. Ohne Brain sende den benötigten Verlauf selbst mit.

Wo diese API bewusst von OpenAI abweicht

Für Chat Completions und Responses kann ein bestehender OpenAI-Client grundsätzlich die Routing-Basisadresse verwenden. Beachte dabei die folgenden Unterschiede. Die Datei- und Live-Transkription hat einen eigenen Vertrag mit Aufträgen, Sitzungen und Verbindungstickets.

  1. Abbrechen ist auf jedem Endzustand ein erfolgreicher Nichtvorgang. POST /responses/{response_uuid}/cancel antwortet auch dann mit dem Zustand der Antwort, wenn diese längst abgeschlossen, fehlgeschlagen oder bereits abgebrochen ist. Der Aufruf ist damit ohne Idempotenzschlüssel wiederholbar; das Ergebnis hängt am Zustand des Auftrags, nicht an der Zahl der Aufrufe.
  2. Eine abgebrochene Verbindung setzt nichts fort. Reisst die Verbindung während einer synchronen oder gestreamten Anfrage ab, gibt es keine Fortsetzungsmarke: die Anfrage wird neu gestartet und erneut abgerechnet. Bereits entstandene Kosten bleiben bestehen. Nur ein gespeicherter Hintergrundauftrag lässt sich weiter beobachten, über starting_after, und dieser Abruf startet keinen neuen Modellaufruf.
  3. Die Verlaufsverdichtung ist opt-in. Passt der selbst gesendete Verlauf nicht in das Eingabefenster, wird die Anfrage mit 400 context_length_exceeded abgelehnt statt stillschweigend gekürzt. Mit context_compression: true erlaubst du die Zusammenfassung ausdrücklich; sie ist ein zusätzlicher kostenpflichtiger Modellaufruf und wird in usage.flowai.compression einzeln ausgewiesen.
  4. Die Websuche ist standardmässig aus. web_search schaltet die native Suche des Anbieters ein und wird zusätzlich abgerechnet. Ein Modell, dessen Suche fest eingebaut ist, lehnt umgekehrt false ab, statt die bezahlte Suche heimlich doch auszuführen.
  5. Ohne Angabe gilt das Modellmaximum an Ausgabetokens. Es wird kein stiller Standardwert eingesetzt, und eine Angabe über dem Maximum des Modells wird mit 400 invalid_field_value und der Nennung dieses Maximums abgelehnt, statt gekürzt zu werden.
  6. Dateien gehen an das gewählte Modell, nicht ins Brain. Chat Completions und Responses nehmen file_id aus POST /files, Direktbytes und https-URLs an. Bilder und Videos sieht nur ein Modell, das den Typ führt, sonst 400 unsupported_for_model. Dokumente, die das Modell nicht selbst liest, werden als Text extrahiert. Audio, das das Modell nicht selbst hört, wird vorher transkribiert und separat abgerechnet. Endnutzerdateien unter /end_users bleiben Textdokumente. Direktbytes sind auf 8 MiB je Anfrage begrenzt. Liegt die Proxy-Grenze darunter, bleiben file_id und URL nutzbar.

Authentifizierung

Verwende ausschließlich Authorization: Bearer YOUR_API_TOKEN. Weder die Endnutzerkennung noch die Modellwahl ersetzt die Authentifizierung. JSON-Anfragen benötigen Content-Type: application/json. Alle Pfade auf dieser Seite sind relativ zur selben Domain; /flowai-routing ist die Dokumentationsseite, kein zusätzlicher API-Prefix.

🤖 Modelle

Konkretes Modell auswählen

GET /api/flowai/v1/models liefert mit einem Routing-Schlüssel ausschließlich freigegebene, bepreiste Anbietermodelle. Wähle für Routing einen Eintrag mit vollständiger Kennung im Format anbieter/modellkennung. Übernimm dessen id unverändert als model.

Die Beispiele verwenden groq/openai/gpt-oss-120b als Muster. Prüfe vor der Nutzung, ob diese Kennung in deiner aktuellen Modellliste enthalten ist, und ersetze sie gegebenenfalls. Verfügbarkeit, Kontextgrenzen und unterstützte Dateiformate hängen vom Modell ab.

Die Preise stehen unter pricing.prompt und pricing.completion als Eurobetrag je einer Million Tokens, mit pricing.currency: EUR und pricing.unit: per_million_tokens. Die API liefert genaue Dezimalzeichenfolgen; die Modellübersicht rundet die Anzeige auf zwei Nachkommastellen. Diese Anzeigerundung verändert die Abrechnung nicht. Die Preise enthalten die für dein Team geltende Marge. Die Modellübersicht im FlowAI-API-Modul verwendet dieselbe Preisquelle. Die Liste ist paginiert: Verwende bei has_more: true den Wert aus last_id als after. Die Modellkennung kann selbst weitere Schrägstriche enthalten.

Transkriptionsmodelle besitzen stattdessen transcription für Fähigkeiten und Grenzen sowie pricing.unit: per_minute und pricing.variants für die bepreisten Betriebsarten und Optionen. Diese Modelle werden über die Audio-Endpunkte aufgerufen. Audio- und Text-Tokenpreise können zusätzlich ausgewiesen sein, wenn der Anbieter anhand tatsächlicher Tokens abrechnet.

Was ein Modelleintrag aussagt

kind sagt, wofür das Modell gedacht ist: chat, embedding, image, video, audio, realtime oder other. Chat Completions und Responses nehmen ausschließlich Modelle mit kind chat an; jedes andere Modell wird mit 400 unsupported_for_model und param model abgelehnt, bevor Guthaben reserviert wird. Für Nicht-Chat-Modelle stehen alle Merkmale unter capabilities auf false.

context_length ist das Kontextfenster des Anbieters, flowai_limits.input_tokens dagegen die Grenze, die FlowAI tatsächlich zulässt. Die beiden Werte können abweichen; maßgeblich für deine Anfrage ist der kleinere aus flowai_limits. Ein Wert null bedeutet, dass keine Quelle eine Angabe macht, und niemals „unbegrenzt“.

supported_parameters nennt die Anfragefelder, die dieses Modell wirklich auswertet, in der Schreibweise dieser API. Ein Feld, das dort fehlt, wird mit 400 unsupported_for_model abgelehnt statt stillschweigend verworfen. capabilities beschreibt dieselbe Auskunft als Merkmale, etwa ob Reasoning, Websuche oder ein natives JSON-Schema zur Verfügung stehen. Die Rohangaben des Anbieters stehen unverändert unter provider_metadata; sie sind je Anbieter unterschiedlich aufgebaut und ausdrücklich keine Zusicherung.

GET /models/{modellkennung} liefert denselben Eintrag einzeln. Die Kennung wird unverändert übernommen, einschließlich enthaltener Schrägstriche. Unbekannte Kennungen und Modelle ohne gepflegten Preis beantworten beide 404 model_not_found.

Modelle auflisten

GET /api/flowai/v1/models

Listet die verfügbaren Modell-Aliase des abonnementgebundenen Schlüssels auf. Der Cursor ist jeweils der öffentliche Modell-Alias.

Query-Parameter:

limit integer Anzahl der Einträge von 1 bis 100, Standard 100
after string Alias aus last_id der vorherigen Seite

Ein Modell abrufen

GET /api/flowai/v1/models/{model_id}

Liefert einen einzelnen Modelleintrag mit Preisen, Fähigkeiten und den tatsächlich geltenden FlowAI-Grenzen.

🧮 Embeddings

Nur ausgewiesene Embedding-Modelle

POST /embeddings erzeugt Vektoren für eigene Texte. Verwendbar sind ausschließlich die dafür freigegebenen Embedding-Modelle, derzeit openai/text-embedding-3-small und openai/text-embedding-3-large. Ein Sprachmodell wird mit 400 unsupported_for_model abgelehnt, bevor Guthaben reserviert wird.

Eine Eingabe oder viele

input ist entweder eine Zeichenfolge oder eine Liste von Zeichenfolgen. Ein Stapel umfasst höchstens 2.048 Einträge mit je höchstens 8.192 Zeichen; überschreitest du eine der beiden Grenzen, wird die Anfrage abgelehnt und nicht gekürzt. Der gesamte Stapel wird in einem Anbieteraufruf verarbeitet und einmal abgerechnet. Die Reihenfolge der Antwort entspricht der Reihenfolge deiner Eingabe; index nennt sie zusätzlich.

Zahlenliste oder Base64

Ohne Angabe erhältst du die Vektoren als Zahlenliste. Mit encoding_format: base64 erhältst du stattdessen die Base64-Darstellung der Werte als 32-Bit-Gleitkommazahlen in Little-Endian-Reihenfolge. Das ist das Format, das die OpenAI-SDKs erwarten, und es überträgt deutlich weniger Bytes. usage.cost und usage.currency weisen den Endkundenbetrag in Euro aus, wie bei jeder anderen kostenpflichtigen Anfrage.

Vektoren erzeugen

POST /api/flowai/v1/embeddings

Erzeugt Einbettungsvektoren für eine Zeichenfolge oder einen Stapel von Zeichenfolgen.

Request Body:

model string * Kennung eines freigegebenen Embedding-Modells im Format anbieter/modellkennung
input string|array * Eine Zeichenfolge oder bis zu 2.048 Zeichenfolgen mit je höchstens 8.192 Zeichen
encoding_format string float (Standard) oder base64 für Little-Endian-Float32
dimensions integer Gewünschte Vektorlänge, sofern das Modell sie unterstützt
user string Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung

🎙️ Audio transkribieren

Modell und Zusatzinformationen wählen

Dateien und Live-Audio verwenden eigene Endpunkte. Jedes Transkript enthält text, bei Stille auch eine leere Zeichenfolge. timestamps und diarize sind standardmäßig deaktiviert. Zeitstempel und anonyme Sprecherkennungen erscheinen nur auf ausdrücklichen Wunsch in segments. Sprecherkennungen identifizieren keine realen Personen. Nicht unterstützte Optionen und Sprachcodes werden vor dem kostenpflichtigen Anbieteraufruf mit HTTP 422 abgelehnt.

ModellDateiLiveZusatzinformationen
groq/whisper-large-v3-turboJaNeinZeitstempel
groq/whisper-large-v3JaNeinZeitstempel
openai/gpt-transcribeJaNeinText
openai/gpt-4o-transcribe-diarizeBis 24 MiBNeinSprecher erforderlich, Zeitstempel optional
openai/gpt-live-transcribeNeinJaText
deepgram/nova-3JaJaZeitstempel und Sprecher

Datei- und Live-Transkription werden getrennt freigeschaltet. Verwende nur Modelle aus deiner aktuellen Antwort von GET /models. Dort beschreiben transcription.modes, transcription.languages und die Optionsfelder die Fähigkeiten. pricing.variants enthält die verfügbaren Kombinationen aus Betriebsart, Zeitstempeln und Sprecherzuordnung, mit Preisen in EUR je Minute und gegebenenfalls je einer Million Audio- oder Text-Tokens. Ein fehlender Preis verhindert den Start; es gibt keinen automatischen Anbieterwechsel.

Dateien und Hintergrundaufträge

Sende die Datei als multipart/form-data direkt an POST /audio/transcriptions. Eine zuvor hochgeladene file_id wird hier nicht angenommen. Die Beispiele im Codebereich starten einen Hintergrundauftrag. Lass background weg oder setze es auf false, wenn du synchron arbeiten möchtest. Überlasse dem HTTP-Client den Multipart-Header einschließlich seiner Boundary.

  • Synchron: höchstens 24 MiB und zehn Minuten, HTTP 200 mit Ergebnis.
  • Im Hintergrund: background=true, grundsätzlich höchstens 200 MiB und acht Stunden, HTTP 202 mit Auftrags-ID. Modellgrenzen gelten zusätzlich.
  • Sprecher: Das OpenAI-Sprechermodell benötigt diarize=true und bleibt auch im Hintergrund auf 24 MiB beschränkt. Für große Aufnahmen mit durchgängiger Sprecherzuordnung wähle ausdrücklich Deepgram.

Frage GET /audio/transcriptions/{id} ab, bis status den Wert completed, cancelled oder failed hat. Davor sind queued und processing möglich. progress liegt zwischen 0 und 1. Das Ergebnis enthält außerdem model, usage, flowai_request_id und expires_at. Bei angeforderten Zeitstempeln beziehen sich start und end auf die gesamte Aufnahme, auch wenn sie in Abschnitten verarbeitet wird.

POST /audio/transcriptions/{id}/cancel verhindert weitere Abschnitte; ein bereits bezahlter Anbieteraufruf darf noch abgeschlossen werden. Bei Fehler oder Abbruch können bestätigte Teilergebnisse vorliegen. DELETE /audio/transcriptions/{id} löscht nur abgeschlossene Aufträge. Große Groq- und gewöhnliche OpenAI-Aufnahmen werden in begrenzte Abschnitte zerlegt und in Originalreihenfolge zusammengesetzt.

Live-Sitzung erstellen und verbinden

POST /audio/transcription-sessions erwartet model und source: push für Audio aus deiner App oder url mit einem direkten öffentlichen HTTP(S)-Audiostream in url. Optional sind language, timestamps, diarize und max_seconds. Die Standardlaufzeit beträgt zwei Stunden, die Höchstlaufzeit acht Stunden. Gleichzeitig sind höchstens drei aktive Sitzungen je Team möglich.

Die Antwort mit HTTP 201 liefert id, websocket_url, ticket und ticket_expires_at. Das Ticket gilt 60 Sekunden, ist an die Sitzung gebunden und wird beim Verbinden einmalig verbraucht. Übertrage es als WebSocket-Unterprotokoll flowai-ticket.TICKET. POST /audio/transcription-sessions/{id}/connection-ticket stellt ein neues Ticket aus und ersetzt das vorherige. Routing- und Anbieterschlüssel gehören nicht in die WebSocket-URL.

Apps senden binäre Frames mit PCM16 Little Endian, mono, 24 kHz. Das sind 48.000 Bytes pro Sekunde. Jeder Frame muss eine gerade Bytezahl und höchstens 48.000 Bytes enthalten; sende in Wiedergabegeschwindigkeit. Bei URL-Quellen dekodiert der Server das Audio; der Client empfängt nur Ereignisse. Private Netzwerkziele, Zugangsdaten in URLs, HLS-Playlists und Plattformseiten werden nicht unterstützt. MP4/M4A-Streams benötigen Metadaten vor den Audiodaten oder fragmentiertes MP4; Dateien mit nachgelagerten Metadaten gehören an den Datei-Endpunkt.

Mit {"type":"audio.commit"} schließt du einen OpenAI-Sprachabschnitt ab; der Server tut dies spätestens nach jeweils zehn Sekunden Audio. {"type":"session.stop"} oder POST /audio/transcription-sessions/{id}/stop beendet die Aufnahme und verarbeitet ausstehende Ergebnisse. Zustände sind waiting, running, stopping und anschließend completed oder failed.

Ereignisse und Wiederverbindung

  • session.ready: Die Client-Verbindung steht. Audio kann während des Anbieterstarts kurz gepuffert werden.
  • transcript.partial: Ersetze den bisherigen Entwurf derselben section_id durch text. Zwischenstände werden nicht dauerhaft gespeichert.
  • transcript.final: Bestätigter Text mit stabiler id, fortlaufender sequence und optionalen segments. Entferne den zugehörigen Entwurf und vermeide Duplikate anhand der ID.
  • connection.interrupted: Unterbrechung mit reason und audio_replayed:false.
  • usage: Bisherige Audiodauer und Abrechnungsstatus. Den genauen EUR-Betrag liefert der REST-Abruf.
  • session.completed: Abschluss mit status, gegebenenfalls error und Audiodauer.

Speichere die letzte bestätigte Sequenznummer. Nach einer Client-Wiederverbindung rufst du GET /audio/transcription-sessions/{id}?after_sequence=N ab. Jede Seite enthält höchstens 1.000 bestätigte Abschnitte; folge next_after_sequence bis last_sequence. text enthält den Text dieser Seite. WebSocket-Ereignisse und REST-Abruf können sich überschneiden, deshalb musst du nach ID deduplizieren.

Eine getrennte Push-Verbindung kannst du innerhalb von 30 Sekunden mit einem neuen Ticket wieder anbinden; danach wird die Aufnahme beendet. OpenAI-Verbindungen werden nach 50 Minuten kontrolliert erneuert. Abschnittsreihenfolge und Aufnahmeversatz bleiben erhalten. Sprecherkennungen enthalten einen Präfix je Anbieter-Verbindung. Unklar verarbeitetes Audio wird nicht automatisch erneut kostenpflichtig gesendet. Ungesendetes Audio wird höchstens im Umfang von fünf Sekunden gepuffert; bei Überschreitung endet die Sitzung kontrolliert.

Direkten Audiostream beobachten

Dieses Beispiel läuft mit Node.js ab Version 22. Setze FLOWAI_URL, FLOWAI_API_KEY und FLOWAI_AUDIO_URL in deinem Backend. Es beobachtet den Stream für 30 Sekunden und fordert dann den Abschluss an.

const response = await fetch(`${process.env.FLOWAI_URL}/api/flowai/v1/audio/transcription-sessions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FLOWAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'deepgram/nova-3', source: 'url',
    url: process.env.FLOWAI_AUDIO_URL, language: 'de',
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const session = await response.json();
const socket = new WebSocket(session.websocket_url, [`flowai-ticket.${session.ticket}`]);
let timer;
socket.addEventListener('open', () => {
  timer = setTimeout(() => socket.send(JSON.stringify({type: 'session.stop'})), 30000);
});
socket.addEventListener('message', ({data}) => {
  const event = JSON.parse(data);
  console.log(event);
  if (event.type === 'session.completed') socket.close();
});
socket.addEventListener('close', () => clearTimeout(timer));
socket.addEventListener('error', () => console.error('WebSocket connection failed'));

Abrechnung, Aufbewahrung und Fehler

Dateiaufträge reservieren vor dem ersten Anbieteraufruf die geschätzten Gesamtkosten. Live-Sitzungen reservieren zunächst 60 Sekunden und erweitern die Reservierung, bevor weiteres Audio übertragen wird. Preise hängen von Modell, Datei-/Live-Betrieb und kostenpflichtigen Zusatzoptionen ab. Auch Stille kann kostenpflichtig sein; Groq rechnet mindestens zehn Sekunden je Anbieteraufruf ab, auch je Dateiabschnitt. Verfügbare tatsächliche Anbieter-Tokens werden berücksichtigt. usage.cost und usage.cost_micro_eur zeigen abgerechnete Kosten, keine noch offenen Reservierungen.

Verwende für die Erstellung einen Idempotency-Key und wiederhole bei unklarer Antwort dieselbe Anfrage mit demselben Schlüssel. Eine Ticket-Erneuerung erhält einen neuen Idempotenzschlüssel. Guthaben, Schlüsselsperren und Teamgrenzen gelten auch während der Verarbeitung. Unklare Anbieterfehler können eine offene Reservierung hinterlassen, bis der Verbrauch geklärt ist.

Fertige Ergebnisse bleiben 24 Stunden nach Abschluss abrufbar. expires_at beschreibt diese Aufbewahrungsfrist, ticket_expires_at ausschließlich die Ticketgültigkeit. Uploads und Arbeitsdateien werden nach Abschluss, Abbruch oder Fehler gelöscht. Abgeschlossene Live-Sitzungen löschst du mit DELETE /audio/transcription-sessions/{id}.

Typische Fehler: HTTP 422 bei ungeeigneten Optionen, Grenzen oder Quellen; HTTP 429 bei zu vielen parallelen Sitzungen; HTTP 503 mit audio_disabled, audio_model_unavailable oder audio_pricing_unavailable, wenn die Funktion, das Modell oder der Preis nicht verfügbar ist. Ein WebSocket-Upgrade mit ungültigem, abgelaufenem oder bereits verbrauchtem Ticket wird abgelehnt. Bei angenommenen Aufträgen und Sitzungen prüfst du zusätzlich status und error; ein erfolgreicher Statusabruf bedeutet noch keine erfolgreiche Transkription.

Datei transkribieren

POST /api/flowai/v1/audio/transcriptions

Datei transkribieren. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.

Request Body:

model string * Freigegebene Kennung anbieter/modell aus GET /models
language string Modellabhängiger Sprachcode, beispielsweise de
timestamps boolean Zeitstempel ausdrücklich aktivieren; Standard false
diarize boolean Anonyme Sprecherzuordnung aktivieren; Standard false
file file * Audiodatei, maximal 200 MiB und acht Stunden, Modellgrenzen beachten
background boolean Über 24 MiB oder zehn Minuten erforderlich. Antwort 202 mit Auftrags-ID.

Auftrag abrufen

GET /api/flowai/v1/audio/transcriptions/{id}

Auftrag abrufen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.

Auftrag abbrechen

POST /api/flowai/v1/audio/transcriptions/{id}/cancel

Auftrag abbrechen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.

Abgeschlossenen Auftrag löschen

DELETE /api/flowai/v1/audio/transcriptions/{id}

Abgeschlossenen Auftrag löschen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.

Live-Sitzung erstellen

POST /api/flowai/v1/audio/transcription-sessions

Live-Sitzung erstellen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.

Request Body:

model string * Freigegebene Kennung anbieter/modell aus GET /models
language string Modellabhängiger Sprachcode, beispielsweise de
timestamps boolean Zeitstempel ausdrücklich aktivieren; Standard false
diarize boolean Anonyme Sprecherzuordnung aktivieren; Standard false
source string * push für Apps oder url für direkte HTTP(S)-Audiostreams
url string Bei source=url erforderlich. Keine privaten Ziele, Zugangsdaten oder HLS-Playlists.
max_seconds integer Standard 7200, maximal 28800 Sekunden

Sitzung und bestätigte Abschnitte abrufen

GET /api/flowai/v1/audio/transcription-sessions/{id}

Sitzung und bestätigte Abschnitte abrufen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.

Query-Parameter:

after_sequence integer Nur spätere bestätigte Abschnitte abrufen, maximal 1000 pro Seite

Neues Verbindungsticket anfordern

POST /api/flowai/v1/audio/transcription-sessions/{id}/connection-ticket

Neues Verbindungsticket anfordern. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.

Aufnahme beenden und Ergebnisse abschließen

POST /api/flowai/v1/audio/transcription-sessions/{id}/stop

Aufnahme beenden und Ergebnisse abschließen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.

Abgeschlossene Sitzung löschen

DELETE /api/flowai/v1/audio/transcription-sessions/{id}

Abgeschlossene Sitzung löschen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.

💬 Chat-Completions

Verlauf selbst verwalten oder Brain nutzen
Ohne external_identifier bleibt die Kontextverwaltung beim Client. Mit Kennung ergänzt Brain den gespeicherten Verlauf, Erinnerungen und relevante Dateiabschnitte. Beide Varianten unterstützen Streaming.

Eine Unterhaltung beginnen

Das folgende Beispiel führt einen Routing-Aufruf ohne gespeicherten Endnutzerkontext aus. Ersetze den Token und wähle ein Modell aus deiner aktuellen Modellliste. Sende für Brain zusätzlich external_identifier als JSON-Zeichenfolge mit. Die vollständige Modellkennung und der Routing-Schlüssel bleiben in beiden Varianten gleich.

Eigene Funktionen aufrufen lassen

Du kannst dem Modell eigene Funktionen anbieten. FlowAI führt diese Funktionen nicht aus. Das Modell entscheidet, welche Funktion mit welchen Argumenten aufgerufen werden soll, du führst den Aufruf in deinem eigenen System aus und sendest das Ergebnis im nächsten Zug zurück. Der Ablauf besteht deshalb immer aus zwei abgerechneten Anfragen.

Erster Zug. Du sendest tools und optional tool_choice:

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [{"role": "user", "content": "Wie ist das Wetter in Berlin?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Aktuelles Wetter einer Stadt.",
      "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }
  }]
}

Die Antwort trägt finish_reason: "tool_calls", content: null und die gewünschten Aufrufe. arguments ist eine Zeichenkette mit JSON, kein Objekt:

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{"city":"Berlin"}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Zweiter Zug ohne Brain. Du sendest den bisherigen Verlauf, die Nachricht des Modells und dein Ergebnis als Nachricht mit role: "tool". Die tool_call_id muss der id aus dem Aufruf entsprechen, sonst antwortet die API mit HTTP 400:

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [
    {"role": "user", "content": "Wie ist das Wetter in Berlin?"},
    {"role": "assistant", "tool_calls": [{"id": "call_abc", "type": "function", "function": {"name": "get_weather", "arguments": "{"city":"Berlin"}"}}]},
    {"role": "tool", "tool_call_id": "call_abc", "content": "12 Grad, bewölkt"}
  ],
  "tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}]
}

Beim Streaming kommen die Aufrufe in einem eigenen Chunk unmittelbar vor dem Abschlusschunk: choices[0].delta.tool_calls enthält den vollständigen Eintrag samt index, der Abschlusschunk trägt finish_reason: "tool_calls". Auf dem Endpunkt Responses erscheinen die Aufrufe stattdessen als Einträge vom Typ function_call in output, und du antwortest im nächsten Zug mit einem Eintrag vom Typ function_call_output.

Zweiter Zug mit Brain. Sende dieselbe external_identifier, die zurückgegebene conversation-UUID und nur das Tool-Ergebnis. Der gespeicherte Assistant-Aufruf bleibt serverseitig und die tool_call_id wird gegen diesen gespeicherten Call geprüft. Den gesamten alten Verlauf noch einmal mitzusenden erzeugt doppelten Kontext.

flowai_tools steuert etwas anderes, nämlich die serverseitigen Werkzeuge von FlowAI. Beide Felder zusammen in einer Anfrage werden mit HTTP 400 und invalid_field_value abgelehnt.

Routing mit Chat-Completions

POST /api/flowai/v1/chat/completions

Sendet Nachrichten an ein freigegebenes Anbietermodell. Ohne Endnutzerkennung verwaltet der Client den Verlauf; mit Kennung ergänzt Brain den persönlichen Kontext.

Request Body:

model string * Vollständige Kennung aus GET /models im Format anbieter/modellkennung
external_identifier string Aktiviert Brain-Kontext für deine stabile Endnutzerkennung mit 1 bis 255 Zeichen; im JSON-Body
messages array * Neue Nachrichten mit role und content; mindestens eine nicht leere Nutzernachricht
conversation uuid UUID aus der vorherigen Antwort desselben Endnutzers; für eine neue Unterhaltung weglassen
max_tokens integer Obergrenze der Ausgabe, 1 bis 128.000. Ohne Angabe gilt das Maximum des Modells; ist für das Modell keines hinterlegt, greifen 4.096 Tokens
stream boolean true liefert Chat-Completions-Chunks als SSE; Standard false
context_compression boolean Erlaubt, einen zu langen selbst gesendeten Verlauf serverseitig zusammenzufassen; Standard false. Ohne diese Angabe wird ein zu langer Verlauf mit 400 context_length_exceeded abgelehnt statt gekürzt. Die Zusammenfassung ist ein zusätzlicher kostenpflichtiger Modellaufruf und wird in usage.flowai.compression ausgewiesen
reasoning_effort string Denktiefe des Modells: none, minimal, low, medium, high, xhigh oder max. Ohne Angabe gilt der Standard des Anbieters, es entsteht also kein Denkbudget, das du nicht angefordert hast. Welche Stufen ein Modell annimmt, steht in capabilities.reasoning_levels aus GET /models; eine nicht unterstützte Stufe wird mit HTTP 400 und unsupported_for_model abgelehnt
web_search boolean Schaltet die native Websuche des Anbieters ein. Standard ist aus, weil jede Suche zusätzlich abgerechnet wird. Modelle ohne native Suche lehnen true ab, Modelle mit fest eingebauter Suche (Perplexity, Groq Compound) lehnen false ab, jeweils mit HTTP 400 und unsupported_for_model; maßgeblich sind web_search und web_search_forced aus GET /models
response_format object Ausgabeform: {"type":"text"}, {"type":"json_object"} oder {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. Die Felder json_object und json_schema aus GET /models sagen, was das Modell nativ beherrscht; fehlt die Fähigkeit, antwortet die API mit HTTP 400 und unsupported_for_model, statt still Fließtext zu liefern
tools array Deine eigenen Funktionen im Format [{"type":"function","function":{"name":…,"description":…,"parameters":<JSON-Schema>}}]. Höchstens 64 Einträge, jedes Schema höchstens 16.384 Bytes als JSON. FlowAI führt diese Funktionen nicht aus: Das Modell antwortet mit tool_calls, du führst die Funktion in deinem eigenen System aus und sendest das Ergebnis als Nachricht mit role "tool" zurück. Ob ein Modell Funktionen annimmt, steht in tools aus GET /models; fehlt die Fähigkeit, antwortet die API mit HTTP 400 und unsupported_for_model. Zusammen mit flowai_tools ist das Feld nicht erlaubt und wird mit HTTP 400 und invalid_field_value abgelehnt
tool_choice string|object Steuert die Werkzeugwahl: "auto", "none", "required" oder {"type":"function","function":{"name":…}} für genau eine Funktion. Nur zusammen mit tools erlaubt, und der genannte Name muss in tools vorkommen. Ohne Angabe gilt der Standard des Anbieters
parallel_tool_calls boolean Erlaubt oder verbietet mehrere Funktionsaufrufe in einer Antwort. Nur zusammen mit tools erlaubt. Nicht jedes Modell kennt diesen Schalter; maßgeblich ist parallel_tool_calls aus GET /models, sonst antwortet die API mit HTTP 400 und unsupported_for_model
max_completion_tokens integer Dieselbe Angabe wie max_tokens, unter dem Namen der Responses-API. Beide zugleich mit unterschiedlichen Werten werden abgelehnt
stream_options object Nimmt ausschliesslich include_usage an und setzt stream: true voraus. Mit include_usage: true folgt ein abschliessender Chunk, der den Verbrauch der gestreamten Antwort nennt
user string Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung, bis 128 Zeichen. Diese Kennung ersetzt external_identifier nicht und aktiviert keinen Brain-Kontext

Chat-Completions als SSE

POST /api/flowai/v1/chat/completions SSE / Streaming SSE

Sendet Nachrichten an ein freigegebenes Anbietermodell. Ohne Endnutzerkennung verwaltet der Client den Verlauf; mit Kennung ergänzt Brain den persönlichen Kontext.

Request Body:

model string * Vollständige Kennung aus GET /models im Format anbieter/modellkennung
external_identifier string Aktiviert Brain-Kontext für deine stabile Endnutzerkennung mit 1 bis 255 Zeichen; im JSON-Body
messages array * Neue Nachrichten mit role und content; mindestens eine nicht leere Nutzernachricht
conversation uuid UUID aus der vorherigen Antwort desselben Endnutzers; für eine neue Unterhaltung weglassen
max_tokens integer Obergrenze der Ausgabe, 1 bis 128.000. Ohne Angabe gilt das Maximum des Modells; ist für das Modell keines hinterlegt, greifen 4.096 Tokens
stream boolean true liefert Chat-Completions-Chunks als SSE; Standard false
context_compression boolean Erlaubt, einen zu langen selbst gesendeten Verlauf serverseitig zusammenzufassen; Standard false. Ohne diese Angabe wird ein zu langer Verlauf mit 400 context_length_exceeded abgelehnt statt gekürzt. Die Zusammenfassung ist ein zusätzlicher kostenpflichtiger Modellaufruf und wird in usage.flowai.compression ausgewiesen
reasoning_effort string Denktiefe des Modells: none, minimal, low, medium, high, xhigh oder max. Ohne Angabe gilt der Standard des Anbieters, es entsteht also kein Denkbudget, das du nicht angefordert hast. Welche Stufen ein Modell annimmt, steht in capabilities.reasoning_levels aus GET /models; eine nicht unterstützte Stufe wird mit HTTP 400 und unsupported_for_model abgelehnt
web_search boolean Schaltet die native Websuche des Anbieters ein. Standard ist aus, weil jede Suche zusätzlich abgerechnet wird. Modelle ohne native Suche lehnen true ab, Modelle mit fest eingebauter Suche (Perplexity, Groq Compound) lehnen false ab, jeweils mit HTTP 400 und unsupported_for_model; maßgeblich sind web_search und web_search_forced aus GET /models
response_format object Ausgabeform: {"type":"text"}, {"type":"json_object"} oder {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. Die Felder json_object und json_schema aus GET /models sagen, was das Modell nativ beherrscht; fehlt die Fähigkeit, antwortet die API mit HTTP 400 und unsupported_for_model, statt still Fließtext zu liefern
tools array Deine eigenen Funktionen im Format [{"type":"function","function":{"name":…,"description":…,"parameters":<JSON-Schema>}}]. Höchstens 64 Einträge, jedes Schema höchstens 16.384 Bytes als JSON. FlowAI führt diese Funktionen nicht aus: Das Modell antwortet mit tool_calls, du führst die Funktion in deinem eigenen System aus und sendest das Ergebnis als Nachricht mit role "tool" zurück. Ob ein Modell Funktionen annimmt, steht in tools aus GET /models; fehlt die Fähigkeit, antwortet die API mit HTTP 400 und unsupported_for_model. Zusammen mit flowai_tools ist das Feld nicht erlaubt und wird mit HTTP 400 und invalid_field_value abgelehnt
tool_choice string|object Steuert die Werkzeugwahl: "auto", "none", "required" oder {"type":"function","function":{"name":…}} für genau eine Funktion. Nur zusammen mit tools erlaubt, und der genannte Name muss in tools vorkommen. Ohne Angabe gilt der Standard des Anbieters
parallel_tool_calls boolean Erlaubt oder verbietet mehrere Funktionsaufrufe in einer Antwort. Nur zusammen mit tools erlaubt. Nicht jedes Modell kennt diesen Schalter; maßgeblich ist parallel_tool_calls aus GET /models, sonst antwortet die API mit HTTP 400 und unsupported_for_model
max_completion_tokens integer Dieselbe Angabe wie max_tokens, unter dem Namen der Responses-API. Beide zugleich mit unterschiedlichen Werten werden abgelehnt
stream_options object Nimmt ausschliesslich include_usage an und setzt stream: true voraus. Mit include_usage: true folgt ein abschliessender Chunk, der den Verbrauch der gestreamten Antwort nennt
user string Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung, bis 128 Zeichen. Diese Kennung ersetzt external_identifier nicht und aktiviert keinen Brain-Kontext

📨 Responses

Antwortmodus wählen

Einfacher Text steht in input; strukturierte Nachrichten sind ebenfalls möglich. Lies den Text aus output[].content[] mit type: output_text. Ohne Zusatzoption erhältst du synchron JSON. stream: true liefert SSE-Ereignisse. background: true startet einen Hintergrundauftrag und antwortet ohne Streaming mit HTTP 202. Beide Optionen lassen sich kombinieren.

Response-Aufbewahrung

Mit store: true bleiben Response und Ereignisse für 24 Stunden nach Abschluss abrufbar. Im Hintergrund ist Speicherung standardmäßig aktiviert, sonst deaktiviert. background: true darf nicht mit store: false kombiniert werden. Eine nicht gespeicherte Antwort ist nach Abschluss nicht per GET abrufbar. Response-Aufbewahrung ist vom dauerhaften Brain-Gesprächsverlauf getrennt.

Polling und SSE-Fortsetzung

Rufe gespeicherte Antworten unter GET /responses/{response_uuid} ab. Für Ereignisse verwende ?stream=true. Speichere die letzte sequence_number aus einem Ereignis; mit starting_after=N erhältst du ausschließlich spätere Ereignisse. Ein solcher Abruf startet keinen neuen Modellaufruf. Der Cursor ist eine nicht negative Ganzzahl und benötigt stream=true. Abgelaufene, nicht gespeicherte und fremde Responses liefern 404 response_not_found.

Ein unterbrochener Beobachtungsstream beendet einen Hintergrundauftrag nicht. Du kannst ihn erneut beobachten oder über POST /responses/{response_uuid}/cancel abbrechen. Bereits entstandene Kosten bleiben bestehen. Für Ergebnisse per Webhook registriere ein Ziel und sende dessen UUID als webhook_endpoint_id mit.

Routing mit Responses

POST /api/flowai/v1/responses

Alternative mit input statt messages, synchron, als SSE oder im Hintergrund. Eine Endnutzerkennung ergänzt optional Brain-Kontext.

Request Body:

model string * Vollständige Kennung aus GET /models im Format anbieter/modellkennung
external_identifier string Aktiviert Brain-Kontext für deine stabile Endnutzerkennung mit 1 bis 255 Zeichen; im JSON-Body
input string|array * Neue Nutzernachricht als Text oder unterstützte Nachrichtenstruktur
conversation uuid UUID aus der vorherigen Antwort desselben Endnutzers; für eine neue Unterhaltung weglassen
stream boolean Antwortereignisse als SSE empfangen; auch mit background kombinierbar
background boolean Im Hintergrund ausführen; ohne stream folgt HTTP 202 mit Response-ID
store boolean Response und Ereignisse für 24 Stunden nach Abschluss abrufbar halten; Standard bei background true, sonst false
webhook_endpoint_id uuid Registriertes Webhook-Ziel für einen Hintergrundauftrag
max_output_tokens integer Obergrenze der Ausgabe, 1 bis 128.000. Ohne Angabe gilt das Maximum des Modells; ist für das Modell keines hinterlegt, greifen 4.096 Tokens
context_compression boolean Erlaubt, einen zu langen selbst gesendeten Verlauf serverseitig zusammenzufassen; Standard false. Ohne diese Angabe wird ein zu langer Verlauf mit 400 context_length_exceeded abgelehnt statt gekürzt. Die Zusammenfassung ist ein zusätzlicher kostenpflichtiger Modellaufruf und wird in usage.flowai.compression ausgewiesen
reasoning.effort string Denktiefe des Modells: none, minimal, low, medium, high, xhigh oder max, auf diesem Endpunkt im Objekt reasoning statt als reasoning_effort. Welche Stufen ein Modell annimmt, steht in capabilities.reasoning_levels aus GET /models. Ohne Angabe gilt der Standard des Anbieters; eine für das Modell unbekannte Stufe wird mit HTTP 400 und unsupported_for_model abgelehnt
web_search boolean Schaltet die native Websuche des Anbieters ein. Standard ist aus, weil jede Suche zusätzlich abgerechnet wird. Modelle ohne native Suche lehnen true ab, Modelle mit fest eingebauter Suche (Perplexity, Groq Compound) lehnen false ab, jeweils mit HTTP 400 und unsupported_for_model; maßgeblich sind web_search und web_search_forced aus GET /models
response_format object Ausgabeform wie bei Chat-Completions: {"type":"text"}, {"type":"json_object"} oder {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. Die Antwort spiegelt sie als text.format mit flach eingebettetem Schema zurück; ohne Angabe enthält die Antwort kein Feld text
tools array Deine eigenen Funktionen, in derselben Schreibweise wie bei Chat-Completions: [{"type":"function","function":{"name":…,"parameters":<JSON-Schema>}}]. Die Antwort spiegelt sie in der Responses-Schreibweise mit flachem name zurück; gesendet wird jedoch immer die verschachtelte Form. FlowAI führt die Funktionen nicht aus
tool_choice string|object Wie bei Chat-Completions: "auto", "none", "required" oder ein Objekt, das genau eine Funktion nennt. Beide Schreibweisen werden angenommen, {"type":"function","name":…} ebenso wie {"type":"function","function":{"name":…}}
parallel_tool_calls boolean Erlaubt oder verbietet mehrere Funktionsaufrufe in einer Antwort. Nur zusammen mit tools erlaubt. Nicht jedes Modell kennt diesen Schalter; maßgeblich ist parallel_tool_calls aus GET /models, sonst antwortet die API mit HTTP 400 und unsupported_for_model
stream_options object Nimmt ausschliesslich include_usage an und setzt stream: true voraus. Mit include_usage: true folgt ein abschliessender Chunk, der den Verbrauch der gestreamten Antwort nennt
user string Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung, bis 128 Zeichen. Diese Kennung ersetzt external_identifier nicht und aktiviert keinen Brain-Kontext
metadata object Bis zu 16 Zeichenkettenpaare, die mit der gespeicherten Antwort aufbewahrt und in ihr zurückgegeben werden. Auf Chat-Completions wird das Feld abgelehnt, weil dort nichts gespeichert wird

Responses als SSE

POST /api/flowai/v1/responses SSE / Streaming SSE

Alternative mit input statt messages, synchron, als SSE oder im Hintergrund. Eine Endnutzerkennung ergänzt optional Brain-Kontext.

Request Body:

model string * Vollständige Kennung aus GET /models im Format anbieter/modellkennung
external_identifier string Aktiviert Brain-Kontext für deine stabile Endnutzerkennung mit 1 bis 255 Zeichen; im JSON-Body
input string|array * Neue Nutzernachricht als Text oder unterstützte Nachrichtenstruktur
conversation uuid UUID aus der vorherigen Antwort desselben Endnutzers; für eine neue Unterhaltung weglassen
stream boolean Antwortereignisse als SSE empfangen; auch mit background kombinierbar
background boolean Im Hintergrund ausführen; ohne stream folgt HTTP 202 mit Response-ID
store boolean Response und Ereignisse für 24 Stunden nach Abschluss abrufbar halten; Standard bei background true, sonst false
webhook_endpoint_id uuid Registriertes Webhook-Ziel für einen Hintergrundauftrag
max_output_tokens integer Obergrenze der Ausgabe, 1 bis 128.000. Ohne Angabe gilt das Maximum des Modells; ist für das Modell keines hinterlegt, greifen 4.096 Tokens
context_compression boolean Erlaubt, einen zu langen selbst gesendeten Verlauf serverseitig zusammenzufassen; Standard false. Ohne diese Angabe wird ein zu langer Verlauf mit 400 context_length_exceeded abgelehnt statt gekürzt. Die Zusammenfassung ist ein zusätzlicher kostenpflichtiger Modellaufruf und wird in usage.flowai.compression ausgewiesen
reasoning.effort string Denktiefe des Modells: none, minimal, low, medium, high, xhigh oder max, auf diesem Endpunkt im Objekt reasoning statt als reasoning_effort. Welche Stufen ein Modell annimmt, steht in capabilities.reasoning_levels aus GET /models. Ohne Angabe gilt der Standard des Anbieters; eine für das Modell unbekannte Stufe wird mit HTTP 400 und unsupported_for_model abgelehnt
web_search boolean Schaltet die native Websuche des Anbieters ein. Standard ist aus, weil jede Suche zusätzlich abgerechnet wird. Modelle ohne native Suche lehnen true ab, Modelle mit fest eingebauter Suche (Perplexity, Groq Compound) lehnen false ab, jeweils mit HTTP 400 und unsupported_for_model; maßgeblich sind web_search und web_search_forced aus GET /models
response_format object Ausgabeform wie bei Chat-Completions: {"type":"text"}, {"type":"json_object"} oder {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. Die Antwort spiegelt sie als text.format mit flach eingebettetem Schema zurück; ohne Angabe enthält die Antwort kein Feld text
tools array Deine eigenen Funktionen, in derselben Schreibweise wie bei Chat-Completions: [{"type":"function","function":{"name":…,"parameters":<JSON-Schema>}}]. Die Antwort spiegelt sie in der Responses-Schreibweise mit flachem name zurück; gesendet wird jedoch immer die verschachtelte Form. FlowAI führt die Funktionen nicht aus
tool_choice string|object Wie bei Chat-Completions: "auto", "none", "required" oder ein Objekt, das genau eine Funktion nennt. Beide Schreibweisen werden angenommen, {"type":"function","name":…} ebenso wie {"type":"function","function":{"name":…}}
parallel_tool_calls boolean Erlaubt oder verbietet mehrere Funktionsaufrufe in einer Antwort. Nur zusammen mit tools erlaubt. Nicht jedes Modell kennt diesen Schalter; maßgeblich ist parallel_tool_calls aus GET /models, sonst antwortet die API mit HTTP 400 und unsupported_for_model
stream_options object Nimmt ausschliesslich include_usage an und setzt stream: true voraus. Mit include_usage: true folgt ein abschliessender Chunk, der den Verbrauch der gestreamten Antwort nennt
user string Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung, bis 128 Zeichen. Diese Kennung ersetzt external_identifier nicht und aktiviert keinen Brain-Kontext
metadata object Bis zu 16 Zeichenkettenpaare, die mit der gespeicherten Antwort aufbewahrt und in ihr zurückgegeben werden. Auf Chat-Completions wird das Feld abgelehnt, weil dort nichts gespeichert wird

Responses im Hintergrund

POST /api/flowai/v1/responses

Startet einen gespeicherten Hintergrundauftrag und antwortet mit HTTP 202. Verwende die Response-ID für Polling, SSE und Abbruch.

Request Body:

model string * Vollständige Kennung aus GET /models im Format anbieter/modellkennung
external_identifier string Aktiviert Brain-Kontext für deine stabile Endnutzerkennung mit 1 bis 255 Zeichen; im JSON-Body
input string|array * Neue Nutzernachricht als Text oder unterstützte Nachrichtenstruktur
conversation uuid UUID aus der vorherigen Antwort desselben Endnutzers; für eine neue Unterhaltung weglassen
stream boolean Antwortereignisse als SSE empfangen; auch mit background kombinierbar
background boolean Im Hintergrund ausführen; ohne stream folgt HTTP 202 mit Response-ID
store boolean Response und Ereignisse für 24 Stunden nach Abschluss abrufbar halten; Standard bei background true, sonst false
webhook_endpoint_id uuid Registriertes Webhook-Ziel für einen Hintergrundauftrag
max_output_tokens integer Obergrenze der Ausgabe, 1 bis 128.000. Ohne Angabe gilt das Maximum des Modells; ist für das Modell keines hinterlegt, greifen 4.096 Tokens
context_compression boolean Erlaubt, einen zu langen selbst gesendeten Verlauf serverseitig zusammenzufassen; Standard false. Ohne diese Angabe wird ein zu langer Verlauf mit 400 context_length_exceeded abgelehnt statt gekürzt. Die Zusammenfassung ist ein zusätzlicher kostenpflichtiger Modellaufruf und wird in usage.flowai.compression ausgewiesen
reasoning.effort string Denktiefe des Modells: none, minimal, low, medium, high, xhigh oder max, auf diesem Endpunkt im Objekt reasoning statt als reasoning_effort. Welche Stufen ein Modell annimmt, steht in capabilities.reasoning_levels aus GET /models. Ohne Angabe gilt der Standard des Anbieters; eine für das Modell unbekannte Stufe wird mit HTTP 400 und unsupported_for_model abgelehnt
web_search boolean Schaltet die native Websuche des Anbieters ein. Standard ist aus, weil jede Suche zusätzlich abgerechnet wird. Modelle ohne native Suche lehnen true ab, Modelle mit fest eingebauter Suche (Perplexity, Groq Compound) lehnen false ab, jeweils mit HTTP 400 und unsupported_for_model; maßgeblich sind web_search und web_search_forced aus GET /models
response_format object Ausgabeform wie bei Chat-Completions: {"type":"text"}, {"type":"json_object"} oder {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. Die Antwort spiegelt sie als text.format mit flach eingebettetem Schema zurück; ohne Angabe enthält die Antwort kein Feld text
tools array Deine eigenen Funktionen, in derselben Schreibweise wie bei Chat-Completions: [{"type":"function","function":{"name":…,"parameters":<JSON-Schema>}}]. Die Antwort spiegelt sie in der Responses-Schreibweise mit flachem name zurück; gesendet wird jedoch immer die verschachtelte Form. FlowAI führt die Funktionen nicht aus
tool_choice string|object Wie bei Chat-Completions: "auto", "none", "required" oder ein Objekt, das genau eine Funktion nennt. Beide Schreibweisen werden angenommen, {"type":"function","name":…} ebenso wie {"type":"function","function":{"name":…}}
parallel_tool_calls boolean Erlaubt oder verbietet mehrere Funktionsaufrufe in einer Antwort. Nur zusammen mit tools erlaubt. Nicht jedes Modell kennt diesen Schalter; maßgeblich ist parallel_tool_calls aus GET /models, sonst antwortet die API mit HTTP 400 und unsupported_for_model
stream_options object Nimmt ausschliesslich include_usage an und setzt stream: true voraus. Mit include_usage: true folgt ein abschliessender Chunk, der den Verbrauch der gestreamten Antwort nennt
user string Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung, bis 128 Zeichen. Diese Kennung ersetzt external_identifier nicht und aktiviert keinen Brain-Kontext
metadata object Bis zu 16 Zeichenkettenpaare, die mit der gespeicherten Antwort aufbewahrt und in ihr zurückgegeben werden. Auf Chat-Completions wird das Feld abgelehnt, weil dort nichts gespeichert wird

Hintergrundauftrag direkt als SSE beobachten

POST /api/flowai/v1/responses SSE / Streaming SSE

Kombiniert background und stream. Der Worker läuft bei einer Unterbrechung des Beobachtungsstreams weiter.

Request Body:

model string * Vollständige Kennung aus GET /models im Format anbieter/modellkennung
external_identifier string Aktiviert Brain-Kontext für deine stabile Endnutzerkennung mit 1 bis 255 Zeichen; im JSON-Body
input string|array * Neue Nutzernachricht als Text oder unterstützte Nachrichtenstruktur
conversation uuid UUID aus der vorherigen Antwort desselben Endnutzers; für eine neue Unterhaltung weglassen
stream boolean Antwortereignisse als SSE empfangen; auch mit background kombinierbar
background boolean Im Hintergrund ausführen; ohne stream folgt HTTP 202 mit Response-ID
store boolean Response und Ereignisse für 24 Stunden nach Abschluss abrufbar halten; Standard bei background true, sonst false
webhook_endpoint_id uuid Registriertes Webhook-Ziel für einen Hintergrundauftrag
max_output_tokens integer Obergrenze der Ausgabe, 1 bis 128.000. Ohne Angabe gilt das Maximum des Modells; ist für das Modell keines hinterlegt, greifen 4.096 Tokens
context_compression boolean Erlaubt, einen zu langen selbst gesendeten Verlauf serverseitig zusammenzufassen; Standard false. Ohne diese Angabe wird ein zu langer Verlauf mit 400 context_length_exceeded abgelehnt statt gekürzt. Die Zusammenfassung ist ein zusätzlicher kostenpflichtiger Modellaufruf und wird in usage.flowai.compression ausgewiesen
reasoning.effort string Denktiefe des Modells: none, minimal, low, medium, high, xhigh oder max, auf diesem Endpunkt im Objekt reasoning statt als reasoning_effort. Welche Stufen ein Modell annimmt, steht in capabilities.reasoning_levels aus GET /models. Ohne Angabe gilt der Standard des Anbieters; eine für das Modell unbekannte Stufe wird mit HTTP 400 und unsupported_for_model abgelehnt
web_search boolean Schaltet die native Websuche des Anbieters ein. Standard ist aus, weil jede Suche zusätzlich abgerechnet wird. Modelle ohne native Suche lehnen true ab, Modelle mit fest eingebauter Suche (Perplexity, Groq Compound) lehnen false ab, jeweils mit HTTP 400 und unsupported_for_model; maßgeblich sind web_search und web_search_forced aus GET /models
response_format object Ausgabeform wie bei Chat-Completions: {"type":"text"}, {"type":"json_object"} oder {"type":"json_schema","json_schema":{"name":…,"schema":…,"strict":…}}. Die Antwort spiegelt sie als text.format mit flach eingebettetem Schema zurück; ohne Angabe enthält die Antwort kein Feld text
tools array Deine eigenen Funktionen, in derselben Schreibweise wie bei Chat-Completions: [{"type":"function","function":{"name":…,"parameters":<JSON-Schema>}}]. Die Antwort spiegelt sie in der Responses-Schreibweise mit flachem name zurück; gesendet wird jedoch immer die verschachtelte Form. FlowAI führt die Funktionen nicht aus
tool_choice string|object Wie bei Chat-Completions: "auto", "none", "required" oder ein Objekt, das genau eine Funktion nennt. Beide Schreibweisen werden angenommen, {"type":"function","name":…} ebenso wie {"type":"function","function":{"name":…}}
parallel_tool_calls boolean Erlaubt oder verbietet mehrere Funktionsaufrufe in einer Antwort. Nur zusammen mit tools erlaubt. Nicht jedes Modell kennt diesen Schalter; maßgeblich ist parallel_tool_calls aus GET /models, sonst antwortet die API mit HTTP 400 und unsupported_for_model
stream_options object Nimmt ausschliesslich include_usage an und setzt stream: true voraus. Mit include_usage: true folgt ein abschliessender Chunk, der den Verbrauch der gestreamten Antwort nennt
user string Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung, bis 128 Zeichen. Diese Kennung ersetzt external_identifier nicht und aktiviert keinen Brain-Kontext
metadata object Bis zu 16 Zeichenkettenpaare, die mit der gespeicherten Antwort aufbewahrt und in ihr zurückgegeben werden. Auf Chat-Completions wird das Feld abgelehnt, weil dort nichts gespeichert wird

Antwortstatus abrufen

GET /api/flowai/v1/responses/{response_uuid}

Liefert eine gespeicherte Routing-Response desselben Teams innerhalb ihrer Aufbewahrungsfrist.

Gespeicherten Ereignisstream fortsetzen

GET /api/flowai/v1/responses/{response_uuid} SSE / Streaming SSE

Liefert nur Ereignisse nach der gespeicherten sequence_number, ohne einen neuen Modellaufruf zu starten.

Query-Parameter:

stream boolean * true für SSE
starting_after integer Letzte empfangene sequence_number; ab 0, exklusiver Cursor

Antwort abbrechen

POST /api/flowai/v1/responses/{response_uuid}/cancel

Fordert idempotent den Abbruch eines Hintergrundauftrags an und liefert dessen aktuellen Zustand.

💬 Unterhaltungen fortsetzen

UUID der vorherigen Antwort mitsenden

Sende beim nächsten Aufruf dieselbe external_identifier, die zurückgegebene conversation-UUID und nur die neuen Nachrichten. Der vorhandene Verlauf wird serverseitig ergänzt. Wenn du den gesamten alten Verlauf noch einmal mitsendest, entsteht doppelter Kontext.

{
  "model": "groq/openai/gpt-oss-120b",
  "external_identifier": "customer-42",
  "conversation": "018f1234-5678-7abc-9def-0123456789ab",
  "messages": [{"role": "user", "content": "Gib mir dazu drei konkrete nächste Schritte."}]
}

Eine Anfrage ohne conversation beginnt eine neue Unterhaltung. Eine unbekannte oder zu einem anderen Workspace beziehungsweise Endnutzer gehörende UUID ergibt 404 conversation_not_found. Für dieselbe Unterhaltung darf nur ein Aufruf gleichzeitig laufen; konkurrierende Aufrufe erhalten 409 conversation_in_progress.

Verlauf, Dateien und Erinnerungen

Brain ergänzt den gespeicherten Gesprächsverlauf und relevante Erinnerungen sowie Dateiabschnitte derselben Person. Der Kontext wird an das Tokenbudget des Modells angepasst. Lange Verläufe werden schrittweise zusammengefasst; auch diese Modellaufrufe gehören zum kostenpflichtigen Verbrauch. Fehlerhafte Zusammenfassungen ersetzen keinen gültigen gespeicherten Stand. Ohne Endnutzerkennung verwaltet der Client den Verlauf und es wird kein persönlicher Brain-Kontext gesucht.

👥 Endnutzerverwaltung

Löschung mit Aufbewahrungspflicht
Die Löschung entfernt persönliche Arbeitsdaten. Abrechnungs- und Verbrauchszeilen bleiben aus Aufbewahrungsgründen erhalten.

Externe Kennung und öffentliche UUID

external_identifier ist deine eigene stabile Zeichenfolge, zum Beispiel customer-42. Damit ordnest du Anfragen innerhalb deines Workspace einem Endnutzer zu. Auch numerische Kennungen müssen als JSON-Zeichenfolge gesendet werden. Der erste Inferenzaufruf ohne conversation legt einen unbekannten Endnutzer automatisch an.

Mit POST /end-users kannst du den Endnutzer vorher anlegen oder auflösen. Die zurückgegebene id ist die öffentliche UUID für Verwaltungs- und Datei-Endpunkte. Diese UUID ist von deiner externen Kennung und von der conversation-UUID zu unterscheiden.

Verlaufsverdichtung

Mit external_identifier liegt der Verlauf bei uns. Wird er länger als das Eingabefenster des Modells, fassen wir die älteren Turns zusammen und speichern diese Zusammenfassung. Jeder Turn wird dadurch genau einmal verdichtet und genau einmal bezahlt. Eine feste Zahl der jüngsten gespeicherten Turns bleibt dabei immer im Wortlaut erhalten; alles davor erreicht das Modell ausschließlich über die Zusammenfassung. Verloren geht nichts: ein Turn verlässt den Wortlaut erst, nachdem die Zusammenfassung ihn aufgenommen hat.

Ohne external_identifier gehört der Verlauf dir, und wir fassen nichts von selbst zusammen. Passt der gesendete Verlauf nicht in das Eingabefenster, antworten wir mit 400 context_length_exceeded; die Meldung nennt max_input_tokens und estimated_input_tokens. Sende dann weniger Nachrichten, oder setze context_compression: true und erlaube damit ausdrücklich die Verdichtung. Diese Verdichtung ist ein zusätzlicher kostenpflichtiger Modellaufruf je Anfrage und wird im Antwortblock usage.flowai.compression mit calls, input_tokens, output_tokens und cost_micro_eur ausgewiesen. Ohne Verdichtung fehlt das Feld.

Metadaten und automatische Erinnerungen

Metadaten enthalten höchstens 50 Einträge mit Schlüsseln bis 64 Zeichen und Zeichenfolgen bis 1.000 Zeichen oder null als Wert. Automatische Erinnerungsextraktion ist bei neuen Endnutzern standardmäßig aktiviert, sobald du Brain mit external_identifier verwendest. Ein zusätzliches Opt-in ist nicht erforderlich. Ohne externe Kennung wird kein Brain verwendet. Deaktiviere die Extraktion bei Bedarf mit PATCH /end-users/{end_user_uuid} und memory_extraction_enabled: false. Bereits ausdrücklich deaktivierte Einstellungen bleiben erhalten.

Endnutzerdaten löschen

DELETE /end-users/{end_user_uuid} entfernt die persönlichen Arbeitsdaten dieser Person aus der API-Nutzung. Private Dateiobjekte werden anschließend im Hintergrund gelöscht; vorübergehende Speicherfehler werden erneut versucht. deleted: true bestätigt daher nicht den bereits abgeschlossenen physischen Löschvorgang aller Objekte. Abrechnungs- und Verbrauchsdaten bleiben erhalten. Unbekannte und fremde UUIDs liefern dieselbe Antwort mit 404 end_user_not_found.

Löschbeleg abrufen

GET /end_users/{end_user_uuid}/erasures listet die Löschvorgänge zu dieser Kennung, GET /end_users/{end_user_uuid}/erasures/{run_uuid} liefert einen einzelnen Beleg. Beide bleiben nach der Löschung abrufbar, denn genau dann brauchst du den Nachweis. status nennt den Stand, requested_at den Zeitpunkt deiner Anforderung und completed_at den Abschluss oder null, solange Objekte im Hintergrund entfernt werden.

manifest_summary.resources nennt je Datenart die Anzahl vor und nach dem Vorgang. Der Beleg enthält ausschließlich Zahlen: keine Texte, keine Dateinamen und keine Kennungen. Datenarten ohne öffentliche Bezeichnung werden nicht ausgewiesen.

Endnutzer auflisten

GET /api/flowai/v1/end-users

Listet die Endnutzer des authentifizierten Workspace mit UUID-Cursor auf.

Query-Parameter:

limit integer Anzahl der Einträge von 1 bis 100, Standard 100
after uuid UUID aus last_id der vorherigen Seite

Endnutzer anlegen oder auflösen

POST /api/flowai/v1/end-users

Legt einen Endnutzer anhand deiner stabilen externen Kennung an oder liefert den vorhandenen Datensatz.

Request Body:

external_identifier string * Deine stabile, nicht sensible Kennung für diesen Endnutzer
metadata object Optionale eigene Metadaten

Endnutzer abrufen

GET /api/flowai/v1/end-users/{end_user_uuid}

Liefert einen Endnutzer über seine UUID.

Endnutzer ändern

PATCH /api/flowai/v1/end-users/{end_user_uuid}

Ergänzt Metadaten oder ändert die automatische Erinnerungsextraktion eines Endnutzers.

Request Body:

metadata object Metadaten, die mit den vorhandenen Werten zusammengeführt werden
memory_extraction_enabled boolean Aktiviert oder deaktiviert die automatische Erinnerungsextraktion

Endnutzer löschen

DELETE /api/flowai/v1/end-users/{end_user_uuid}

Löscht die persönlichen Arbeitsdaten eines Endnutzers. Abrechnungs- und Verbrauchszeilen bleiben erhalten.

Löschvorgänge auflisten

GET /api/flowai/v1/end_users/{end_user_uuid}/erasures

Listet die Löschbelege zu einer Endnutzerkennung, auch nach der Löschung.

Query-Parameter:

limit integer Einträge je Seite, 1 bis 100, Standard 20
after string Cursor aus last_id der vorherigen Seite

Löschbeleg abrufen

GET /api/flowai/v1/end_users/{end_user_uuid}/erasures/{run_uuid}

Liefert einen einzelnen Löschbeleg mit Zeitpunkten und Mengenangaben je Datenart.

📎 Dateien als Endnutzerkontext

Dokumente einer Person zuordnen

Lege den Endnutzer an oder löse ihn über POST /end-users auf. Verwende seine öffentliche UUID für POST /end_users/{end_user_uuid}/files. Beachte den Unterstrich in end_users; die Endnutzerverwaltung verwendet dagegen end-users.

Sende die Datei als multipart/form-data mit purpose=user_data. Unterstützt werden PDF, DOCX, XLSX, TXT, Markdown und CSV. Die Standardgrenzen betragen 32 MiB pro Datei, 100 Dateien pro Endnutzer und 5 GiB pro Workspace. Für Multipart-Anfragen erzeugt dein HTTP-Client den Content-Type einschließlich Boundary.

Verarbeitung erfolgt im Hintergrund

Ein erfolgreicher Upload antwortet mit HTTP 201 und status: pending. Erst nach Extraktion und Indizierung stehen passende Textstellen für spätere Routing-Anfragen desselben Endnutzers zur Verfügung. Der Upload bestätigt noch nicht, dass die Datei bereits abrufbarer Gesprächskontext ist. Vorübergehende Verarbeitungsfehler werden erneut versucht; nicht lesbarer Dokumentinhalt kann dauerhaft fehlschlagen.

Auflisten, prüfen, einzeln entfernen

GET /end_users/{end_user_uuid}/files listet die Dateien dieser Person, neueste zuerst, seitenweise über limit und after. status nennt den Stand der Verarbeitung. DELETE /end_users/{end_user_uuid}/files/{file_uuid} entfernt eine einzelne Datei samt der daraus gewonnenen Textabschnitte; die Löschung der gesamten Person ist dafür nicht mehr nötig. Die Datei-ID dieses Uploads gehört weiterhin nicht zur allgemeinen /files-Verwaltung.

Nach dem Löschen verbleibt ein inhaltsfreier Eintrag ohne Dateinamen und ohne Objekt, damit der bereits genutzte Speicher abrechenbar bleibt. Er erscheint in keiner Liste. Unbekannte Dateien, Dateien einer anderen Person und Dateien eines anderen Workspace liefern dieselbe Antwort mit 404 file_not_found.

Endnutzerdatei hochladen

POST /api/flowai/v1/end_users/{end_user_uuid}/files

Speichert eine Textdatei für den Endnutzer und startet ihre Verarbeitung. Verwende multipart/form-data.

Request Body:

file file * Unterstützte Text- oder Dokumentdatei mit Dateiname bis 255 Zeichen
purpose string * Pflichtwert user_data; andere Zwecke werden abgelehnt

Dateien auflisten

GET /api/flowai/v1/end_users/{end_user_uuid}/files

Listet die Dateien eines Endnutzers, neueste zuerst.

Query-Parameter:

limit integer Einträge je Seite, 1 bis 100, Standard 20
after string Cursor aus last_id der vorherigen Seite

Datei abrufen

GET /api/flowai/v1/end_users/{end_user_uuid}/files/{file_uuid}

Liefert die Angaben zu einer einzelnen Datei, ohne deren Inhalt.

Datei löschen

DELETE /api/flowai/v1/end_users/{end_user_uuid}/files/{file_uuid}

Entfernt eine einzelne Datei samt der daraus gewonnenen Textabschnitte.

📎 Dateien des Workspace

Dateien hochladen

Sende Uploads als multipart/form-data. Zulässige Zwecke sind user_data und vision. Eine automatische Aufbewahrungsfrist wird nicht angeboten; nicht mehr benötigte Dateien müssen ausdrücklich gelöscht werden.

Metadaten und Inhalt

Der Einzelabruf liefert nur Metadaten. Die gespeicherten Bytes stehen ausschließlich über den gesonderten Inhaltsendpunkt bereit.

Datei hochladen

POST /api/flowai/v1/files

Speichert eine Datei für spätere FlowAI-Anfragen. Verwende multipart/form-data.

Request Body:

file file * Hochzuladende Datei
purpose string * user_data oder vision

Dateien auflisten

GET /api/flowai/v1/files

Listet die Dateien des Workspace mit stabilem Cursor auf.

Query-Parameter:

purpose string Filter: user_data oder vision
order string Sortierung: asc oder desc
limit integer Anzahl von 1 bis 100
after string Öffentliche Datei-ID aus last_id

Dateimetadaten abrufen

GET /api/flowai/v1/files/{file_uuid}

Liefert Metadaten, aber nicht den Dateiinhalt.

Dateiinhalt herunterladen

GET /api/flowai/v1/files/{file_uuid}/content BINARY

Liefert die gespeicherten Bytes als Download mit dem ursprünglichen Medientyp.

Datei löschen

DELETE /api/flowai/v1/files/{file_uuid}

Löscht die gespeicherten Bytes und ihre Metadaten.

🧠 Erinnerungen

Erinnerungen je Endnutzer

Dieser gemeinsame Endpoint-Vertrag gehört zur Brain-Funktion der Routing-API und benötigt einen Routing-Schlüssel.

Alle Aufrufe binden eine Erinnerung über external_identifier an genau einen Endnutzer. Änderungen verwenden revision zur optimistischen Konflikterkennung.

Auflisten oder suchen

GET /memories beantwortet zwei Fragen über dieselben Einträge. Ohne query erhältst du die Erinnerungen dieser Person chronologisch absteigend, seitenweise über limit und after; dieser Weg ruft kein Modell auf und kostet nichts. Mit query läuft die Ähnlichkeitssuche, die den Suchtext einbettet und daher zum kostenpflichtigen Verbrauch zählt.

Ein Suchergebnis ist eine Rangfolge und keine Seite: die Suche liefert deshalb has_more: false und last_id: null und bietet keinen Cursor an. Ein after-Wert, der nicht aus einer vorherigen Seite stammt, wird mit 400 invalid_cursor abgelehnt und niemals als leere Seite beantwortet.

Kontext für spätere Antworten

Gespeicherte Erinnerungen werden innerhalb desselben Workspace und Endnutzers als relevanter Kontext herangezogen. Das manuelle Anlegen einer Erinnerung benötigt keine aktivierte automatische Extraktion. Bewahre die zurückgegebene revision auf und sende sie beim Ändern mit. Bei 409 memory_revision_conflict musst du den aktuellen Stand erneut abrufen und die Änderung abgleichen.

Erinnerung anlegen

POST /api/flowai/v1/memories

Speichert eine persönliche Erinnerung für einen Endnutzer.

Request Body:

external_identifier string * Stabile externe Endnutzerkennung
text string * Nicht leerer Text mit höchstens 10.000 Zeichen
kind string Optionale Art der Erinnerung
GET /api/flowai/v1/memories

Sucht semantisch in den Erinnerungen eines Endnutzers.

Query-Parameter:

external_identifier string * Deine stabile Endnutzerkennung
query string Suchtext; ohne Angabe werden die Erinnerungen chronologisch aufgelistet
limit integer Einträge je Seite, 1 bis 100, Standard 20
after string Cursor aus last_id der vorherigen Seite; nur beim Auflisten

Erinnerung ändern

PATCH /api/flowai/v1/memories/{memory_uuid}

Ändert eine Erinnerung, wenn die angegebene Revision aktuell ist.

Request Body:

external_identifier string * Stabile externe Endnutzerkennung
text string * Neuer Erinnerungstext
revision integer * Aktuelle Revision, mindestens 1

Erinnerung löschen

DELETE /api/flowai/v1/memories/{memory_uuid}

Löscht eine Erinnerung des angegebenen Endnutzers.

Request Body:

external_identifier string * Stabile externe Endnutzerkennung

🔔 Webhooks

Secret nur einmal sichtbar
Das Signatur-Secret wird ausschließlich beim Anlegen zurückgegeben. Speichere es sicher und veröffentliche es nicht.

Ziele und Signaturen

Webhook-Ziele müssen öffentlich erreichbare HTTPS-Adressen sein. Die API prüft Adressen beim Speichern und erneut vor jeder Zustellung. Registriere mindestens einen unterstützten Ereignistyp.

Zustellungen prüfen

Der Zustellungsverlauf zeigt Status, Versuche und Fehlerart. Zulässige Statusfilter sind pending, delivered, failed und exhausted.

Unterstützte Ereignistypen

Neben den vier Abschlussereignissen eines Hintergrundauftrags (response.completed, response.failed, response.cancelled, response.incomplete) kannst du vier weitere Typen abonnieren: credit.threshold beim Erreichen einer deiner Warnschwellen in Euro (data.metric ist balance_floor, wenn der verfügbare Betrag unter die Schwelle gefallen ist, oder spend_month, wenn der Monatsverbrauch sie erreicht hat; data.threshold_eur nennt den Schwellenbetrag als Dezimalzeichenkette, zum Beispiel "50.00"), credit.topup_failed bei einer fehlgeschlagenen Aufladung, webhook_endpoint.deactivated wenn ein Ziel nach wiederholten Fehlversuchen abgeschaltet wurde, und webhook.test für die selbst ausgelöste Testzustellung. Jede Zustellung hat denselben Aufbau: id, type, created_at und data. webhook_endpoint.deactivated geht bewusst an alle übrigen aktiven Ziele des Workspace, niemals an das gerade abgeschaltete: dieses hat soeben bewiesen, dass es nichts empfangen kann.

Secret wechseln ohne Zustellungslücke

Beim Wechsel bleibt das bisherige Secret bis zum Zeitpunkt aus secondary_secret_expires_at gültig. In diesem Zeitfenster enthält der Kopfzeilenwert webhook-signature zwei durch ein Leerzeichen getrennte Werte der Form v1,<Signatur>, je einen pro Secret. Prüfe alle Werte und akzeptiere die Zustellung beim ersten Treffer. Nach Ablauf des Fensters wird nur noch mit dem neuen Secret signiert. Das Wechseln des Secrets benötigt einen Verwaltungsschlüssel; ein Inferenzschlüssel erhält 403 insufficient_key_scope.

Webhook anlegen

POST /api/flowai/v1/webhook_endpoints

Registriert ein HTTPS-Ziel und gibt das Signatur-Secret einmalig zurück.

Request Body:

url string * Öffentlich erreichbare HTTPS-Adresse, maximal 2.048 Zeichen
events array * Mindestens ein unterstützter Ereignistyp
description string Optionale Beschreibung, maximal 255 Zeichen

Webhooks auflisten

GET /api/flowai/v1/webhook_endpoints

Listet die Webhook-Ziele des Workspace ohne Secrets auf.

Query-Parameter:

limit integer Anzahl von 1 bis 100
after uuid UUID aus last_id

Webhook abrufen

GET /api/flowai/v1/webhook_endpoints/{webhook_uuid}

Liefert ein Webhook-Ziel ohne Signatur-Secret.

Webhook ändern

PATCH /api/flowai/v1/webhook_endpoints/{webhook_uuid}

Ändert Ziel, Ereignisse, Beschreibung oder Aktivierungsstatus.

Request Body:

url string Neue öffentlich erreichbare HTTPS-Adresse
events array Neue Liste unterstützter Ereignistypen
description string Neue Beschreibung oder null
is_active boolean Deaktiviert oder reaktiviert das Ziel

Webhook löschen

DELETE /api/flowai/v1/webhook_endpoints/{webhook_uuid}

Löscht das Ziel und seinen Zustellungsverlauf.

Zustellungen auflisten

GET /api/flowai/v1/webhook_endpoints/{webhook_uuid}/deliveries

Listet Zustellungsversuche mit Status und Fehlerdetails auf.

Query-Parameter:

status string pending, delivered, failed oder exhausted
limit integer Anzahl von 1 bis 100
after uuid UUID aus last_id

Testzustellung senden

POST /api/flowai/v1/webhook_endpoints/{webhook_uuid}/test

Stellt eine synthetische Zustellung vom Typ webhook.test in die Warteschlange. Das Ergebnis erscheint im Zustellungsverlauf.

Secret wechseln

POST /api/flowai/v1/webhook_endpoints/{webhook_uuid}/rotate_secret

Erzeugt ein neues Signatur-Secret und gibt es einmalig zurück. Das bisherige Secret bleibt bis zum genannten Zeitpunkt gültig.

💳 Abrechnung und API-Schlüssel

Eigenes Guthaben in Euro

Routing benötigt kein FlowSuite-Abonnement. Neue Teams starten mit 0 € im Prepaid-Modus. Lade im FlowAI-API-Modul mindestens 20 € auf. Der Aufladebetrag ist der Endbetrag, ohne zusätzliche Steueraufschläge. Kontowerte werden als ganze Micro-EUR geliefert: Eine Million Micro-EUR entsprechen einem Euro.

Vor kostenpflichtiger Verarbeitung werden Mittel reserviert. Danach wird der tatsächliche Verbrauch einschließlich Gesprächskontext, Retrieval und erforderlicher Zusammenfassungen abgerechnet. Verwende usage.cost und usage.currency für den Endkundenbetrag in Euro. Fehlende Preise dürfen nicht als kostenloser Verbrauch interpretiert werden.

Wurde für eine Anfrage Verlauf verdichtet, weist usage.flowai.compression diesen Anteil gesondert aus: calls die Zahl der Zusammenfassungsaufrufe, input_tokens und output_tokens deren Tokens sowie cost_micro_eur deren Kosten in ganzen Micro-EUR. Dieser Betrag steckt bereits in usage.cost; er wird zusätzlich einzeln genannt, damit ein unerwartet hoher Betrag aus der Antwort selbst erklärbar ist. Ohne Verdichtung fehlt das Feld vollständig.

Für gespeicherte Brain-Dateien fällt derzeit keine zusätzliche monatliche Speichergebühr an. Kostenpflichtige Modellverarbeitung, etwa Embeddings und Bildanalyse beim Verarbeiten einer Datei, wird als Modellverbrauch abgerechnet. Die Dateigrößen- und Teamgrenzen gelten weiterhin.

Postpaid nur nach Freischaltung

Nur die Administration kann Postpaid aktivieren. Bei der ersten Freischaltung sind 50 € Kreditrahmen voreingestellt; die Administration kann diesen Betrag pro Team ändern. Guthaben wird zuerst verwendet. Die Monatsrechnung enthält ausschließlich den noch nicht durch Guthaben gedeckten Verbrauch. Offene Forderungen und laufende Reservierungen verringern den nutzbaren Kreditrahmen.

Automatische Aufladung

Automatisches Aufladen ist standardmäßig ausgeschaltet. Aktiviere es ausdrücklich im Modul und wähle eine verifizierte, zum Team gehörende Karte. Die Guthabengrenze beträgt mindestens 5 €, der Aufladebetrag mindestens 20 €. Du kannst die Zustimmung jederzeit widerrufen. Eine Aufladung ändert kein monatliches Schlüssellimit.

Getrennte Schlüssel und Verbrauchsdaten

Erstelle unter FlowAI API → API-Schlüssel einen Schlüssel mit der Berechtigung „KI nutzen“ oder „Schlüssel verwalten“. Diese Schlüssel sind dauerhaft dem Routing-Produkt und einem Abrechnungsteam zugeordnet. Bestehende FlowSuite-Schlüssel werden nicht umgewandelt. Ein Schlüssel mit „Schlüssel verwalten“ kann über /api/user/api-keys nur Schlüssel desselben Produkts verwalten; ohne explizites kind entsteht auch dort ein Schlüssel mit „Schlüssel verwalten“. Modellaufrufe benötigen kind: inference.

GET /credits liefert das EUR-Konto; available_micro_eur ist verfügbares Guthaben, spendable_micro_eur berücksichtigt zusätzlich den freigeschalteten Kreditrahmen. reserved_oldest_at nennt den Zeitpunkt der ältesten noch offenen Reservierung oder null; eine sehr alte Reservierung deutet auf einen Klärungsfall hin, den die Administration auflöst. GET /key zeigt den verwendeten Schlüssel und seine Grenzen. Die Verbrauchsübersicht trennt Routing-Ausgaben von internen Kosten des FlowAI-Abonnements. Belege findest du unter Rechnungen.

Verbrauch auswerten

GET /usage fasst den Verbrauch eines Zeitraums zusammen. start und end sind Tagesangaben im Format JJJJ-MM-TT; ohne Angabe werden die letzten 30 Tage ausgewertet. group_by akzeptiert day (Standard), model, api_key und end_user. requests zählt Anfragen, nicht Anbieteraufrufe: eine Anfrage mit Zusammenfassung und Retrieval bleibt eine Anfrage. cost_micro_eur ist der bereits abgerechnete Endkundenbetrag in Micro-EUR.

GET /usage/requests listet die einzelnen Anfragen, neueste zuerst, seitenweise über limit und after und filterbar nach status, api_key, end_user und model. Die Liste enthält Zeitpunkt, Modell, Anbieter, Status, Fehlercode, Laufzeit, Tokenzahlen und Kosten. Anfrage- und Antworttext sind niemals Teil dieser Auskunft; dafür ist der Support zuständig. Beide Endpunkte sind mit einem Schlüssel für „Schlüssel verwalten“ abrufbar.

provider nennt den Anbieter, bei dem die Anfrage tatsächlich abgerechnet wurde, in derselben Schreibweise wie die erste Hälfte der Modellkennung. Dieses Feld gehört ausschließlich zum Routing-Produkt. Schlüssel des FlowAI-Abonnements erreichen die beiden Verbrauchsendpunkte gar nicht; sie erhalten 403 insufficient_key_scope, und die Anbieternamen hinter den Abo-Modellen bleiben dort unveröffentlicht.

Guthaben abrufen

GET /api/flowai/v1/credits

Liefert das unabhängige EUR-Konto des authentifizierten Routing-Teams, ohne Zahlung oder Modellaufruf.

Verbrauch zusammenfassen

GET /api/flowai/v1/usage

Fasst Anfragen, Tokens und Kosten eines Zeitraums nach Tag, Modell, Schlüssel oder Endnutzer zusammen.

Query-Parameter:

start string Erster Tag im Format JJJJ-MM-TT, Standard 29 Tage vor end
end string Letzter Tag im Format JJJJ-MM-TT, Standard heute
group_by string day, model, api_key oder end_user; Standard day

Einzelne Anfragen auflisten

GET /api/flowai/v1/usage/requests

Listet einzelne Anfragen mit Modell, Anbieter, Status, Laufzeit, Tokenzahlen und Kosten, ohne Anfrage- oder Antworttext.

Query-Parameter:

limit integer Einträge je Seite, 1 bis 100, Standard 20
after string Cursor aus last_id der vorherigen Seite
status string Nur Anfragen mit diesem Status
api_key string UUID eines Schlüssels desselben Workspace
end_user string Externe Endnutzerkennung
model string Modellkennung wie in der Anfrage gesendet

Verwendeten API-Schlüssel prüfen

GET /api/flowai/v1/key

Liefert Status, Schlüsselart und geltende Anfragegrenzen für den authentifizierenden API-Schlüssel.

API-Schlüssel auflisten

GET /api/user/api-keys

Listet die aktiven Schlüssel des authentifizierten Benutzers im authentifizierten Workspace auf. Geheime Tokenwerte werden nie ausgegeben.

API-Schlüssel anlegen

POST /api/user/api-keys

Legt einen Schlüssel im authentifizierten Workspace an und gibt den neuen Tokenwert in dieser Antwort aus.

Request Body:

name string * Anzeigename, maximal 255 Zeichen
kind string inference oder management; Standard management. Für Modellanfragen inference ausdrücklich angeben
expires_at datetime Optionaler Ablaufzeitpunkt in der Zukunft

API-Schlüssel sperren

DELETE /api/user/api-keys/{key_uuid}

Sperrt einen zusätzlichen Schlüssel des authentifizierten Workspace sofort. Persönliche Schlüssel können nur erneuert werden.

API-Schlüssel erneuern

PUT /api/user/api-keys/{key_uuid}/regenerate

Ersetzt den Tokenwert eines Schlüssels im authentifizierten Workspace. Die konfigurierte Übergangsfrist bestimmt, wie lange der vorherige Wert noch gilt.

⚠️ Limits und Fehlerbehandlung

Anfragegrenzen beachten

Standardmäßig gelten 128 KiB für JSON-Anfragen, höchstens 50 Nachrichten und 32.000 Zeichen pro Nachricht. Die Standardlimits betragen 60 Anfragen pro Minute je Workspace, 30 je Modell und einen Burst von 5 pro Sekunde; zusätzlich sind gleichzeitig laufende Anfragen begrenzt. Weitere Token-, Kosten- und Monatsgrenzen können unabhängig davon greifen. Details findest du unter Limits der gemeinsamen API.

Häufige Antworten

  • 400 invalid_field_value: Pflichtfeld, Wert oder Datentyp prüfen.
  • 400 unsupported_field: Ein Feld wird für den gewählten Endpunkt nicht unterstützt. Prüfe dessen Parameterliste. Dieselbe Antwort erhältst du für context_compression, solange die Verlaufsverdichtung abgeschaltet ist.
  • 400 context_length_exceeded: Der gesendete Verlauf passt nicht in das Eingabefenster des Modells. Die Meldung nennt max_input_tokens und estimated_input_tokens; param ist messages. Sende weniger Nachrichten oder setze context_compression: true.
  • 401 invalid_api_key: Token fehlt, ist ungültig, abgelaufen oder gesperrt.
  • 403 insufficient_key_scope: Einen Schlüssel mit „KI nutzen“ verwenden.
  • 403 account_suspended: Der Routing-Zugang dieses Kontos ist gesperrt. Wende dich an den Support; ein erneuter Versuch hilft nicht.
  • 404 model_not_found: Vollständige Kennung mit der aktuellen Modellliste abgleichen.
  • 404 conversation_not_found: Workspace, Endnutzerkennung und Unterhaltungs-UUID prüfen.
  • 409 conversation_in_progress: Vorherigen Aufruf derselben Unterhaltung abwarten.
  • 409 idempotency_key_in_progress: Die Anfrage mit diesem Idempotenzschlüssel läuft noch oder ihr Ergebnis ist nach einem Ausfall nicht sicher bekannt.
  • 413 payload_too_large: JSON-Anfrage verkleinern.
  • 422 idempotency_key_reuse: Derselbe Idempotenzschlüssel wurde für andere Anfragedaten benutzt.
  • 429 rate_limit_exceeded: Die übermittelte Wartezeit beachten.
  • 429 insufficient_quota: Verfügbares Guthaben prüfen.
  • 429 spend_limit_exceeded: Das monatliche Schlüssellimit oder ein freigegebener Kreditrahmen reicht nicht aus; eine Aufladung ändert kein Schlüssellimit.
  • 503 routing_unavailable: Das Routing-Produkt ist vorübergehend abgeschaltet. Die Wartezeit aus dem Header Retry-After beachten; es wird weder Guthaben reserviert noch ein Anbieter aufgerufen.
  • 503 provider_overloaded: Der Anbieter hat gerade keine Kapazität. Die Wartezeit aus dem Header Retry-After beachten und den Aufruf danach wiederholen.
  • 503 pricing_unavailable: Für das Modell ist momentan kein belastbarer Preis verfügbar.

Sicher wiederholen und Fehler zuordnen

Verwende für wiederholte POST-Anfragen einen stabilen Idempotency-Key pro logischem Vorgang. Eine identische, erfolgreich abgeschlossene JSON-Anfrage kann innerhalb des Aufbewahrungsfensters von standardmäßig 24 Stunden erneut beantwortet werden. Geänderte Inhalte oder Dateinamen benötigen einen neuen Schlüssel. Bei einem Verbindungsabbruch kann trotzdem bereits kostenpflichtige Verarbeitung stattgefunden haben; wechsle deshalb nicht automatisch auf einen neuen Schlüssel.

Fehler enthalten error.message, error.type, error.code und gegebenenfalls error.param. Bewahre die flowai_request_id aus der Antwort für Supportanfragen auf. Die gemeinsame Fehlerreferenz enthält weitere Codes für Guthaben und Ausgabengrenzen.

Aufbewahrung deiner Aufrufprotokolle

Zu jedem Aufruf speichern wir ein Protokoll mit Zeitpunkt, Modell, Tokenzahlen, Laufzeit, Status und flowai_request_id. Der übermittelte Anfrageinhalt und der Antworttext werden zusätzlich für die Supportdiagnose vorgehalten und nach 30 Tagen automatisch gelöscht; das Protokoll selbst bleibt als Nachweis für Verbrauch und Abrechnung 400 Tage erhalten. Auf Wunsch deaktivieren wir die Speicherung von Anfrage- und Antworttext für deinen Workspace vollständig, dann enthalten die Protokolle nur noch die genannten technischen Angaben. Ohne diese Inhalte kann der Support einen gemeldeten Aufruf allerdings nicht mehr nachvollziehen.