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

FlowAI API - Ihr FlowAI über die Schnittstelle

Ein Endpunkt, eine Unterhaltung: Sie senden eine Nachricht, erhalten die Antwort und die Kennung der Unterhaltung, und chatten mit dieser Kennung weiter. Verlauf, Werkzeuge und Erinnerungen sind dieselben wie im Web-Chat. Dazu kommen Anhänge und Webhook-Ziele. Anbietermodelle, Endnutzer mit eigenem Brain-Kontext und die Abrechnung nach Verbrauch gehören zum eigenständigen Routing-Produkt.

🚀 Schnellstart

Basis-URL: https://creativeskyline.de/api/flowai/v1
FlowSuite-Zugang: Pro-Tarif erforderlich
Modellaufrufe mit abonnementgebundenen FlowSuite-Schlüsseln benötigen einen aktiven Pro-Tarif. Für FlowAI Routing benötigen Sie kein Abonnement: Dort verwenden Sie eigene Routing-Schlüssel und zahlen nach Verbrauch.

Diese Seite beschreibt Ihr eigenes FlowAI über die Schnittstelle: dieselben Unterhaltungen, dieselben Werkzeuge und dieselben Erinnerungen wie im Web-Chat. Die Fläche ist deshalb klein: der Modellkatalog, ein Chat-Endpunkt, der Dateispeicher für Anhänge und die Webhook-Ziele, an die ein fertiger Lauf sein Ergebnis ausliefern kann.

Alles Weitere, also konkrete Anbietermodelle, Endnutzer mit eigenem Brain-Kontext, Erinnerungen, Embeddings und die Abrechnung nach Verbrauch, gehört zum eigenständigen Produkt FlowAI Routing und benötigt einen Routing-Schlüssel. Ein abonnementgebundener Schlüssel wird dort mit 403 insufficient_key_scope abgewiesen, und umgekehrt ebenso. Das Produkt eines Schlüssels ist unveränderlich.

Voraussetzungen

  • Aktiver Pro-Tarif für Ihren Workspace
  • Inferenzschlüssel aus Profil → API-Zugang; zusätzliche Schlüssel können ein at_-Präfix haben. Entscheidend ist die Schlüsselart, nicht das Präfix
  • HTTP-Client mit Unterstützung für JSON, für den Streaming-Modus zusätzlich für Server-Sent Events

Basis-URL

Beide Endpunkte hängen am gemeinsamen Versions-Prefix:

BASE_URL/api/flowai/v1

Breaking Changes erscheinen unter v2, sodass bestehende Integrationen nicht brechen.

Authentifizierung

Die FlowAI-API akzeptiert nur den Standard-Header Authorization: Bearer …. Token in Query-Parametern, im Body oder in alternativen Headern werden mit HTTP 401 und Code invalid_token_source abgelehnt.

Authorization: Bearer pk_dein_api_key
Accept: application/json
Content-Type: application/json

Die erste Anfrage

POST BASE_URL/api/flowai/v1/chat

{
  "message": "Hallo"
}

Die Antwort enthält conversation. Senden Sie diesen Wert beim nächsten Mal mit, und Sie setzen dieselbe Unterhaltung fort.

🤖 Modelle

Modellwahl nach Produkt
Mit einem abonnementgebundenen Schlüssel enthält die Modellliste ausschließlich stabile logische Modell-Aliase in kebab-case. Routing-Schlüssel liefern stattdessen vollständig qualifizierte Anbietermodelle mit Endkundenpreisen in Euro. Erstellen Sie diese gesondert im FlowAI-API-Modul.

Verfügbare Modelle abfragen

Endpoint: GET /api/flowai/v1/models

Die Antwort enthält die stabilen Modell-Aliase für das FlowSuite-Pro-Abonnement. Sie enthält ausschließlich freigegebene Modelle mit gepflegten Eingabe- und Ausgabepreisen.

{
  "object": "list",
  "data": [
    {"id":"flowai","object":"model","created":1735000000,"owned_by":"creativeskyline"}
  ],
  "flowai_request_id": "01HXYZ…ULID"
}

Modell-Aliase

  • flowai - Allrounder: kombiniert die besten Modelle für jede Aufgabe
  • chatgpt - Kreativ: Brainstorming, Texte, E-Mails, Copywriting
  • claude - Analytisch: lange Dokumente, präzise Anweisungen, Nuancen
  • gemini - Technisch: Datenanalyse, Kalkulationen, multimodal
  • grok - Schnell: prägnante Antworten, Faktencheck, Quick-Lookups
  • perplexity - Recherche: aktuelle Web-Quellen, fundierte Recherche-Antworten
  • flowai-web - Web-Recherche über den API-exklusiven FlowAI-Webmodus

Was ein Modelleintrag aussagt

context_length ist das Kontextfenster des Anbieters, flowai_limits.input_tokens dagegen die Grenze, die FlowAI tatsächlich zulässt; maßgeblich für Ihre Anfrage ist der kleinere Wert. capabilities und supported_parameters nennen die Felder, die dieses Modell wirklich auswertet. Ein Feld, das dort fehlt, wird mit 400 unsupported_for_model abgelehnt statt stillschweigend verworfen. Ein Wert null bedeutet, dass keine Quelle eine Angabe macht, und niemals unbegrenzt.

Abkündigung und Abschalttermin

deprecated_at ist der angekündigte Abschalttermin dieses Modells, sonst null. Bis zu diesem Zeitpunkt bleibt das Modell in der Liste und voll aufrufbar; jede Antwort auf Chat-Completions, Responses und Embeddings trägt dann zusätzlich die Kopfzeilen Deprecation: true und Sunset mit genau diesem Termin nach RFC 8594. Ab dem Termin antwortet die API mit 410 model_deprecated, bevor Guthaben reserviert oder ein Anbieter aufgerufen wird. Ein Abschalttermin wird mindestens 30 Tage im Voraus gesetzt; ein Modell, das der Anbieter selbst aus seinem Katalog nimmt, verschwindet dagegen sofort aus der Liste.

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 Eintrag der Modellliste mit Preisen, Fähigkeiten, den tatsächlich geltenden FlowAI-Grenzen und dem Abschalttermin. Die Kennung ist der Modell-Alias; mit einem Routing-Schlüssel die vollständige Anbieterkennung einschließlich enthaltener Schrägstriche.

💬 Chat

Immer eine Unterhaltung, nie ein Einzelaufruf
Jeder Aufruf gehört zu einer Unterhaltung. Der Verlauf bleibt bei uns, die Kennung der Unterhaltung kommt mit jeder Antwort zurück, und der nächste Zug braucht nur diese Kennung und die nächste Nachricht. Einen zustandslosen Modus gibt es hier nicht; er gehört zur Routing-API.

Die erste Nachricht

Senden Sie message und lassen Sie conversation weg. Die Antwort enthält unter conversation die Kennung der neu angelegten Unterhaltung. Bewahren Sie diesen Wert auf.

{
  "message": "Fasse unsere Liefer­bedingungen zusammen."
}

Weiter chatten

Senden Sie beim nächsten Zug dieselbe conversation und nur die neue Nachricht. Der Verlauf wird serverseitig ergänzt; senden Sie ihn nicht noch einmal mit. Es läuft immer nur ein Zug je Unterhaltung: ein zweiter Aufruf, während der erste noch arbeitet, erhält 409 conversation_in_progress.

Warten oder streamen

Ohne stream wartet der Aufruf auf die Antwort und liefert sie im selben Zug. Mit stream: true erhalten Sie Server-Sent Events: das erste Ereignis trägt type: chat.created mit der Kennung der Unterhaltung, danach folgen die Arbeitsschritte und zuletzt response.completed mit dem vollständigen Text.

Wenn eine Antwort länger braucht

Dauert die Verarbeitung länger als die serverseitige Wartegrenze, antwortet der Aufruf mit HTTP 202 und status: in_progress. Die Antwort ist nicht verloren: GET /api/flowai/v1/chat/{conversation_uuid} liefert den fertigen Zug, sobald er vorliegt.

Was dieser Endpunkt ablehnt

Die Felder messages, input, store, background, external_identifier, tools und flowai_tools gehören zu anderen Endpunkten und werden mit 400 unsupported_field abgelehnt, statt stillschweigend verworfen zu werden.

Nachricht senden

POST /api/flowai/v1/chat

Sendet eine Nachricht an Ihr FlowAI und liefert die Antwort samt Kennung der Unterhaltung.

Request Body:

message string * Die neue Nachricht, 1 bis 32.000 Zeichen
conversation uuid Kennung aus einer vorherigen Antwort; ohne Angabe beginnt eine neue Unterhaltung
model string Modell-Alias aus GET /models; ohne Angabe gilt flowai
stream boolean true liefert die Antwort als Server-Sent Events; Standard false

Letzte Antwort einer Unterhaltung abrufen

GET /api/flowai/v1/chat/{conversation_uuid}

Liefert den neuesten Zug einer Unterhaltung, ohne einen neuen zu starten.

📎 Dateien

Dateien hochladen

Senden Sie 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. Verwenden Sie 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.

🔔 Webhooks

Secret nur einmal sichtbar
Das Signatur-Secret wird ausschließlich beim Anlegen zurückgegeben. Speichern Sie es sicher und veröffentlichen Sie 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. Registrieren Sie 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) können Sie vier weitere Typen abonnieren: credit.threshold beim Erreichen einer Ihrer 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üfen Sie alle Werte und akzeptieren Sie 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 wie jede andere Zustellung.

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. Benötigt einen Verwaltungsschlüssel.

📦 Limits & Rate-Limit

Body-Limits

  • 128 KB Request-Body insgesamt
  • Bis zu 50 Nachrichten pro Request
  • Maximal 32.000 Zeichen Content pro Nachricht

Übergrößen werden mit HTTP 413 und Code payload_too_large abgelehnt.

Rate-Limit

  • 60 Requests/Minute je Workspace
  • 5 Requests/Sekunde Burst je Workspace
  • 30 Requests/Minute je Modell, entsprechend der Hälfte des Workspace-Kontingents
  • Alle API-Schlüssel eines Workspace teilen sich dieses Budget.

Antworten enthalten OpenAI-kompatible Header: x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requests. Der Reset-Wert ist eine Dauer, kein Zeitpunkt, zum Beispiel 1s oder 6m0s.

Eingabe- und Ausgabengrenzen

Die Eingabegrenze zählt geschätzte Tokens in den Nachrichten. Sie ist von der Body-Grenze unabhängig, die Bytes im gesamten Anfragekörper zählt, daher können beide Grenzen unabhängig greifen. Die Ausgabengrenze gilt je Kalendermonat und berücksichtigt bereits verbrauchte sowie für laufende Anfragen reservierte Beträge.

Kein automatischer Gesprächszustand

Chat-Completions speichern keinen serverseitigen Fortsetzungszustand. Senden Sie den benötigten Nachrichtenverlauf bei jedem Aufruf erneut. Hintergrundaufträge sind davon getrennt und können bis zum Ablauf ihrer Aufbewahrungsfrist abgerufen werden.

Keine Fortsetzungsmarke

Beim Abruf eines Hintergrundauftrags wird der Abfrageparameter starting_after nicht unterstützt und mit HTTP 400 abgelehnt. Ein abgebrochener Ablauf lässt sich nicht an einer Ereignismarke fortsetzen, sondern muss neu gestartet werden und verursacht erneut Kosten.

⚠️ Fehlerbehandlung

Einheitliches Fehler-Format

Alle Fehlerantworten haben dieselbe OpenAI-kompatible Struktur. Das Top-Level-Feld flowai_request_id ist immer enthalten.

{
  "error": {
    "message": "Authorization: Bearer header is required on the FlowAI API.",
    "type": "authentication_error",
    "code": "invalid_token_source",
    "param": null
  },
  "flowai_request_id": "01HXYZ…ULID"
}

Häufige Fehlercodes

Diese Liste ist die gemeinsame Fehlerreferenz beider FlowAI-Produkte; die Routing-Anleitung verweist darauf. Codes rund um Endnutzer, Erinnerungen und Unterhaltungen treten deshalb ausschließlich auf den Routing-Endpunkten auf.

  • 400 invalid_field_value - Validierung fehlgeschlagen (Typ, Bereich, Pflichtfeld). Dazu zählt die zu hohe Ausgabegrenze: liegt max_tokens beziehungsweise max_output_tokens über dem Maximum des Modells, nennt die Meldung dieses Maximum. Ohne Angabe gilt das Modellmaximum, gekürzt wird nichts stillschweigend. Ebenso abgelehnt werden flowai_tools und tools in derselben Anfrage
  • 400 invalid_cursor - Der Cursor fehlt, ist leer oder gehört nicht zur aufgerufenen Liste
  • 400 unsupported_field - Feld wird nicht unterstützt, zum Beispiel starting_after
  • 400 unsupported_for_model - Das Feld ist gültig, aber das gewählte Modell nimmt es nicht an, zum Beispiel temperature bei einem Modell mit festem Sampling oder reasoning_effort bei einem Modell ohne Reasoning. param nennt das Feld; die Meldung nennt das Modell und bei Stufenfeldern die zulässigen Werte. Die Modellliste unter /v1/models nennt je Modell die unterstützten Felder
  • 400 input_tokens_exceeded - Die geschätzte Eingabe überschreitet die Tokengrenze; senden Sie weniger Inhalt in den Nachrichten
  • 400 context_length_exceeded - Der gesendete Verlauf passt nicht in das Eingabefenster des Modells; kürzen Sie ihn oder schalten Sie die Verlaufsverdichtung ausdrücklich ein
  • 400 tool_round_limit_exceeded - Die Anfrage hat die zulässige Zahl an Arbeitsschritten erreicht; teilen Sie sie in mehrere Anfragen auf
  • 400 request_cost_limit_exceeded - Die Anfrage hat den zulässigen Rechenaufwand erreicht; kürzen oder teilen Sie die Anfrage
  • 401 invalid_token_source - Token nicht via Authorization: Bearer übergeben
  • 401 invalid_api_key - Token unbekannt, abgelaufen oder widerrufen
  • 401 no_active_subscription - Workspace hat keinen aktiven Pro-Tarif
  • 403 insufficient_key_scope - Der API-Schlüssel ist für diesen Endpunkttyp nicht freigeschaltet
  • 403 account_suspended - Der Routing-Zugang dieses Kontos ist gesperrt; wenden Sie sich an den Support. Schlüssel des Abo-Produkts sind davon nicht betroffen
  • 404 model_not_found - Unbekannter Alias, gültige Aliase siehe /v1/models
  • 404 response_not_found - Antwort unbekannt oder für den Workspace nicht sichtbar
  • 404 conversation_not_found - Unterhaltung unbekannt oder für diesen Endnutzer nicht sichtbar
  • 404 file_not_found - Datei unbekannt oder für den Workspace nicht sichtbar
  • 404 memory_not_found - Erinnerung oder zugehöriger Endnutzer nicht gefunden
  • 404 end_user_not_found - Endnutzer unbekannt oder für den Workspace nicht sichtbar
  • 404 webhook_endpoint_not_found - Webhook unbekannt oder für den Workspace nicht sichtbar
  • 409 conversation_in_progress - In dieser Unterhaltung läuft bereits eine Anfrage
  • 409 idempotency_key_in_progress - Der gleiche Idempotenzschlüssel läuft noch oder sein Ergebnis ist nach einem Fehler unklar
  • 409 memory_revision_conflict - Die Erinnerung wurde zwischenzeitlich geändert
  • 410 model_deprecated - Das Modell ist abgekündigt und seit dem genannten Zeitpunkt nicht mehr aufrufbar; wählen Sie ein Modell aus /v1/models
  • 413 payload_too_large - Request-Body über 128 KB
  • 413 file_too_large - Datei überschreitet die konfigurierte Uploadgrenze
  • 422 idempotency_key_reuse - Derselbe Idempotenzschlüssel wurde mit geänderten Anfragedaten oder einem anderen Dateinamen verwendet
  • 429 rate_limit_exceeded - 60 Requests/Minute je Workspace, 5 Requests/Sekunde Burst je Workspace oder 30 Requests/Minute je Modell überschritten
  • 429 insufficient_quota - Das verfügbare Guthaben reicht für diese Anfrage nicht aus
  • 429 credit_balance_exhausted - Das Guthaben reicht für diese Anfrage nicht aus; eine Aufladung ist erforderlich
  • 429 spend_limit_exceeded - Die vereinbarte Ausgabengrenze ist erreicht; eine Anhebung ist erforderlich
  • 429 period_spend_limit_exceeded - Die Ausgabengrenze des Kalendermonats wäre überschritten; warten Sie bis zum nächsten Monat oder lassen Sie die Grenze anheben, eine Guthabenaufladung allein ändert diese Grenze nicht
  • 502 provider_unavailable - Der gewählte Anbieter ist nicht erreichbar
  • 503 routing_unavailable - Das Routing-Produkt ist vorübergehend abgeschaltet; der Header Retry-After nennt die Wartezeit in Sekunden. Es wird kein Guthaben reserviert und kein Anbieter aufgerufen
  • 503 provider_overloaded - Der gewählte Anbieter hat gerade keine Kapazität; der Header Retry-After nennt die Wartezeit in Sekunden
  • 503 pricing_unavailable - Für das gewählte Modell ist kein belastbarer Preis verfügbar