Einen multimodalen Arbeitsablauf mit der Rivya API erstellen

Eine gute Rivya-API-Integration ist nicht nur eine Anfrage an ein Modell.

Die meisten echten Produktabläufe folgen einer kurzen Kette: das richtige Modell auswählen, Eingaben vorbereiten, bei Bedarf Referenzdateien hochladen, eine Aufgabe senden, ihren Zustand beobachten, Credits verwalten und das Produkt benachrichtigen, sobald das Ergebnis bereit ist.

Dieser Artikel zeigt, wie du den Ablauf planst. Nutze den Schnellstart für die Rivya API für den kürzesten ausführbaren Pfad und die API-Dokumentation für die genauen Anfragefelder.

Der folgende Arbeitsablauf beschreibt den implementierten Vertrag der Public API. Prüfe vor der Entwicklung, ob der Public-API-Zugriff für Bereitstellung und Konto aktiviert ist, ob das gewählte Modell API-bereit ist und ob optionale Funktionen wie Webhooks tatsächlich verfügbar sind.

Mit dem Produktmoment beginnen

Beschreibe den Produktmoment in einem Satz, bevor du Endpunkte auswählst.

Beispiele:

• Erstelle einen Produktbildentwurf, wenn ein Verkäufer die Angaben für ein Angebot einreicht.

• Generiere ein kurzes Videokonzept, nachdem ein Campaign Manager eine Still-Richtung freigegeben hat.

• Sende einen Chat Turn in einem internen Research-Tool und streame die Antwort zurück zum Nutzer.

• Lade ein Referenzbild hoch, sende eine unterstützte Modellanfrage und benachrichtige den Nutzer, wenn das Ergebnis bereit ist.

Dieser Satz verhindert, dass die Integration zu einer losen Sammlung von API-Aufrufen wird.

Den Arbeitsablauf vor dem Programmieren abbilden

Nutze diese Tabelle, bevor du das Anfrageschema öffnest.

Der Arbeitsablauf sollte so klar sein, dass jeder API-Bereich eine begründete Aufgabe hat.

Schritt 1: Einen Key für die Integration erstellen

Erstelle einen API-Schlüssel für die Anwendung, Umgebung oder den Arbeitsablauf, der ihn verwenden wird.

Verwende nicht einen Key für alles. Keys nach Zweck zu benennen macht spätere Reviews einfacher:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

Lies API-Authentifizierung, bevor du den Schlüssel speicherst. Das vollständige Geheimnis wird nur einmal angezeigt; dein Team sollte es daher sofort im passenden serverseitigen Geheimnisspeicher sichern.

Schritt 2: Modelle aus der öffentlichen API-Liste wählen

Hardcode kein Modell nur, weil es in einem manuellen Test funktioniert hat.

Nutze API-Modelle und die API-Referenz für Modelle, um Folgendes zu bestätigen:

• die öffentliche Modell-ID

• ob es über die API verfügbar ist

• unterstützter Eingabemodus

• Anforderungen an Anweisung und Parameter

• ob die Datei-API erforderlich ist

• Credit-Verhalten und Hinweise zur Einsatzbereitschaft

Hier werden viele Integrationen sauberer. Ein Modell, das perfekt für einen manuellen Studio-Test ist, ist nicht zwingend das beste erste Modell für einen automatisierten Produktflow.

Schritt 3: Entscheiden, ob die Datei-API Teil der ersten Version ist

Wenn das Modell mit einer Texteingabe laufen kann, beschränke die erste Version auf Text.

Füge die Datei-API nur hinzu, wenn der Arbeitsablauf wirklich Referenzmedien braucht.

Wenn ja, definiere:

• welche Dateiarten das Produkt akzeptiert

• wer für die Dateibereinigung verantwortlich ist

• was geschieht, wenn das Hochladen fehlschlägt

• wie die zurückgegebenen Dateidaten in Modellparameter übergeben werden

• ob dieselbe Datei wiederverwendet oder erneut hochgeladen werden soll

Das verhindert, dass eine fragile Dateierfahrung hinter einem sauber wirkenden Generate-Button versteckt wird.

Schritt 4: Einen Generierungsjob senden

Für Bild-, Video- und Audiogenerierung ist das normale Muster:

1. Modell-ID, Anweisung und unterstützte Parameter vorbereiten

2. einen Idempotency Key für sichere Retries hinzufügen

3. über den Generierungsendpunkt senden

4. die öffentliche Aufgaben-ID speichern

5. den Zustand regelmäßig abfragen, bis die Aufgabe einen Endzustand erreicht

Nutze Generierung erstellen für die Struktur der Anfrage und Generierungsstatus für die Ergebnisbehandlung.

Das Produkt sollte queued, processing, succeeded und failed als verständliche Zustände anzeigen. Nutzer sollten weder Systemdetails lesen noch erraten müssen, warum eine Aufgabe lange dauert.

Schritt 5: Chat API für Chatmodelle nutzen

Chatmodelle sollten die Chat API nutzen, nicht den Generierungsendpunkt.

Das zählt, weil Chat-Arbeit anderes Verhalten hat:

• Chatnachrichten können zu über die API erstellten Sitzungen gehören

• vollständige Antworten und die Übertragung per SSE bieten unterschiedliche Nutzererlebnisse

• Bildanhänge nutzen Datei-IDs aus der Datei-API

• die Credit-Abrechnung folgt der Chatnachricht statt einer normalen asynchronen Medienaufgabe

Wenn dein Produkt eine Assistant-Antwort in seiner eigenen Oberfläche braucht, kann Chat API der richtige Pfad sein. Wenn der Nutzer noch Ideen exploriert, können Rivya Chat oder Studio besser passen.

Schritt 6: Mit regelmäßigen Statusabfragen starten, dann Webhooks hinzufügen

Für eine erste Version sind regelmäßige Statusabfragen leichter nachzuvollziehen.

Wenn Webhooks für das Deployment aktiviert sind, füge API Webhooks hinzu, wenn:

• das Produkt viele asynchrone Aufgaben hat

• wartende Clients den Status nicht direkt regelmäßig abfragen sollten

• nachgelagerte Systeme signierte Completion Events brauchen

• Retry- und Duplicate-Handling bereits entworfen sind

Webhook Receiver sollten langweilig und strikt sein: Signatur prüfen, duplicate-safe Events akzeptieren, einen Produktrecord aktualisieren und nur sicher loggbare Daten loggen.

Schritt 7: Credits im Produkt sichtbar machen

Die Rivya API nutzt dieselben Konto-Credits wie Studio.

Deine Integration sollte entscheiden, wie viel davon angezeigt wird. Mindestens sollte das Team wissen:

• welchem Konto der API-Schlüssel gehört

• welcher Arbeitsablauf Credits verbrauchen kann

• was passiert, wenn Credits zu niedrig sind

• wie fehlgeschlagene Generierungszustände erklärt werden

• wohin sich jemand mit Fragen zu Credits und Abrechnung wenden soll

Nutze API-Credits, Credits und Abrechnung in Rivya und So funktionieren Rivya-Credits, Pakete und Tarife, um das Guthabenmodell aus Nutzersicht zu verstehen.

Eine kleine erste Version

Eine gute erste Version ist bewusst begrenzt.

Zum Beispiel:

1. ein API Key

2. ein ausgewähltes Bildmodell

3. noch keine Datei hochladen

4. eine Generierungsanfrage

5. ein einfacher Pfad für regelmäßige Statusabfragen

6. eine einfache Ergebnisvorschau in deinem Produkt

7. eine klare Credit-Fehlermeldung

Diese Version beweist die Verbindung, bevor weitere bewegliche Teile dazukommen.

Eine vollständigere Version

Nachdem die erste Version funktioniert, kann ein vollständigerer Arbeitsablauf Folgendes ergänzen:

• Datei-API für Referenzbilder oder Videos

• modellspezifische Parameterkontrollen

• Idempotency, die an deinen Produktrecord gebunden ist

• signierte Webhooks für Completion

• Chat API für Assistant Turns

• einen serverseitigen Ereignisstrom, wenn der Chat Ergebnisse in Echtzeit braucht

• Ansichten für Verwaltung oder Support bei fehlgeschlagenen Aufgaben

Jede Ergänzung sollte einen echten Produktbedarf beantworten. Wenn sie nur die Demo größer wirken lässt, lass sie weg.

Häufige Integrationsfehler

Vermeide diese Muster:

• mit allen API-Features auf einmal zu starten

• die Credit-Nutzung vor dem Kontoinhaber zu verbergen

• Studio-only Annahmen in einen API-Flow zu übernehmen

• das Hochladen von Dateien als Nebensache zu behandeln

• Generierungsanfragen ohne Idempotency zu retryn

• die Chat API für Aufgaben zu nutzen, die asynchron generiert werden sollten

• Generierungsendpunkte für Chatnachrichten zu nutzen

• vollständige API Keys, Webhook Secrets oder temporäre Dateidetails zu loggen

Der sicherste API-Arbeitsablauf regelt Zuständigkeit, Zustand und Fehlerbehandlung ausdrücklich.

Wohin du als Nächstes gehen solltest

• Starte im Bereich Für Entwickler für den öffentlichen API-Einstieg.

• Nutze Rivya API Quickstart, um die erste Anfrage auszuführen.

• Nutze API-Modelle, bevor du Modell-IDs auswählst.

• Nutze die Datei-API nur, wenn das Modell wirklich Referenzmedien braucht.

• Nutze die Chat API für Chatnachrichten und in Echtzeit übertragene Antworten.

• Nutze API Webhooks, wenn regelmäßige Statusabfragen nicht mehr ausreichen.

• Wenn der Arbeitsablauf weiterhin menschliche Erkundung braucht, lies Wann die Rivya API statt Studio sinnvoll ist, bevor du ihn automatisierst.