Einen multimodalen Workflow mit der Rivya API bauen

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

Die meisten echten Produktworkflows haben eine kleine Kette: das richtige Modell wählen, Input vorbereiten, bei Bedarf Referenzdateien hochladen, einen Job senden, Status beobachten, Credits behandeln und das Produkt benachrichtigen, wenn das Ergebnis bereit ist.

Dieser Artikel zeigt die Planungsform. Nutze Rivya API Quickstart für den kürzesten lauffähigen Pfad und die API-Dokumentation für exakte Request-Felder.

Mit dem Produktmoment beginnen

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

Beispiele:

• Erstelle einen Produktbild-Draft, wenn ein Seller einen Listing-Brief sendet.
• 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 Workflow vor dem Code mappen

Nutze diese Tabelle, bevor du das Request-Schema öffnest.

Der Workflow sollte klar genug sein, dass jeder API-Bereich einen Grund hat zu existieren.

Schritt 1: Einen Key für die Integration erstellen

Erstelle einen API Key für die spezifische App, Umgebung oder den Workflow, der ihn nutzen 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 Authentication, bevor du den Key speicherst. Das vollständige Secret wird nur einmal angezeigt, daher sollte dein Team es sofort im richtigen serverseitigen Secret Store 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 Models und Model API Reference, um zu bestätigen:

• die öffentliche Modell-ID
• ob es über die API verfügbar ist
• unterstützter Eingabemodus
• Prompt- und Parametererwartungen
• ob Files API erforderlich ist
• Credit-Verhalten und Readiness-Notizen

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 Files API Teil der ersten Version ist

Wenn das Modell mit Texteingabe laufen kann, halte die erste Version text-only.

Füge Files API nur hinzu, wenn der Workflow wirklich Referenzmedien braucht.

Wenn ja, definiere:

• welche Dateiarten das Produkt akzeptiert
• wem der File-Cleanup-Schritt gehört
• was bei Upload-Fehlern passiert
• 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, Prompt und unterstützte Parameter vorbereiten
2. einen Idempotency Key für sichere Retries hinzufügen
3. über den Generation Endpoint senden
4. die öffentliche Task ID speichern
5. Status poll'en, bis der Task einen terminalen Zustand erreicht

Nutze Create Generation für die Request-Form und Generation Status für Ergebnisbehandlung.

Das Produkt sollte queued, processing, succeeded und failed als nutzerverständliche Zustände behandeln. Lass Nutzer keine Systemdetails lesen oder raten, warum ein Job langsam ist.

Schritt 5: Chat API für Chatmodelle nutzen

Chatmodelle sollten Chat API nutzen, nicht den Generation Endpoint.

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

• Chat Turns können zu API-erstellten Sessions gehören
• Non-streaming und SSE Streaming haben unterschiedliche Nutzererlebnisse
• Bildanhänge nutzen File IDs aus Files API
• Credit Settlement folgt dem Chat Turn statt einem normalen asynchronen Medientask

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 Polling starten, dann Webhooks hinzufügen

Für eine erste Version ist Polling leichter zu durchdenken.

Füge API Webhooks hinzu, wenn:

• das Produkt viele asynchrone Jobs hat
• wartende Clients nicht direkt poll'en 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

Rivya API nutzt dieselben Account Credits wie Studio.

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

• welcher Account den API Key besitzt
• welcher Workflow Credits verbrauchen kann
• was passiert, wenn Credits zu niedrig sind
• wie fehlgeschlagene Generierungszustände erklärt werden
• wohin jemand für Credit- und Billing-Fragen gehen soll

Nutze API Credits, Credits & Billing in Rivya und How to Think About Rivya Credits, Packs, and Plans für das nutzerseitige Wallet-Modell.

Eine kleine erste Version

Eine gute erste Version ist bewusst begrenzt.

Zum Beispiel:

1. ein API Key
2. ein ausgewähltes Bildmodell
3. noch kein Datei-Upload
4. eine Generierungsanfrage
5. ein Status-Polling-Pfad
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, könnte ein vollständigerer Workflow hinzufügen:

• Files 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 Event Stream, wenn Chat Live-Output braucht
• Admin- oder Support-Views für fehlgeschlagene Jobs

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
• Credit-Nutzung vor dem Account Owner zu verstecken
• Studio-only Annahmen in einen API-Flow zu übernehmen
• Datei-Uploads als Nebensache zu behandeln
• Generierungsanfragen ohne Idempotency zu retryn
• Chat API für Jobs zu nutzen, die asynchrone Generierung sein sollten
• Generation Endpoints für Chat Turns zu nutzen
• vollständige API Keys, Webhook Secrets oder temporäre Dateidetails zu loggen

Der sicherste API-Workflow ist explizit in Ownership, Status und Fehlerbehandlung.

Wohin du als Nächstes gehen solltest

• Starte bei Developers für den öffentlichen API-Hub.
• Nutze Rivya API Quickstart, um die erste Anfrage auszuführen.
• Nutze API Models, bevor du Modell-IDs auswählst.
• Nutze Files API nur, wenn das Modell wirklich Referenzmedien braucht.
• Nutze Chat API für Chat Turns und Streaming-Chat-Antworten.
• Nutze API Webhooks, wenn Polling nicht mehr reicht.
• Wenn der Workflow weiterhin menschliche Exploration braucht, lies When to Use Rivya API Instead of Studio, bevor du ihn automatisierst.