Bouw een multimodale workflow met de Rivya API

Een goede integratie met de Rivya API bestaat niet uit slechts één aanvraag aan één model.

De meeste echte productworkflows volgen een korte keten: kies het juiste model, bereid de invoer voor, upload zo nodig referentiebestanden, dien een taak in, volg de status, verwerk de credits en meld in het product dat het resultaat klaar is.

Dit artikel laat zien hoe je die keten plant. Gebruik de Rivya API-snelstart voor het kortste uitvoerbare pad en raadpleeg de API-documentatie voor de exacte aanvraagvelden.

De onderstaande workflow beschrijft het geïmplementeerde contract van de openbare API. Controleer vóór de ontwikkeling of openbare API-toegang voor de implementatie en het account is ingeschakeld, of het gekozen model geschikt is voor de API en of optionele functies zoals webhooks werkelijk beschikbaar zijn.

Begin met het productmoment

Beschrijf het productmoment in één zin voordat je endpoints kiest.

Voorbeelden:

• Maak een productafbeeldingsdraft wanneer een verkoper een listingbrief indient.

• Genereer een kort videoconcept nadat een campaign manager een still-richting goedkeurt.

• Stuur een chat turn in een interne researchtool en stream het antwoord terug naar de gebruiker.

• Upload een referentiebeeld, dien een ondersteunde modelrequest in en notify de gebruiker wanneer het resultaat klaar is.

Die zin voorkomt dat de integratie een losse verzameling API-calls wordt.

Breng de workflow in kaart voordat je code schrijft

Gebruik deze tabel voordat je het requestschema opent.

De workflow moet duidelijk genoeg zijn dat elk API-gebied een reden heeft om te bestaan.

Stap 1: Maak een key voor de integratie

Maak een API-key voor de specifieke app, omgeving of workflow die hem gebruikt.

Gebruik niet één key voor alles. Keys op doel benoemen maakt latere review makkelijker:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

Lees API-authenticatie voordat je de key opslaat. Het volledige secret wordt één keer getoond, dus je team moet het direct opslaan in de juiste server-side secret store.

Stap 2: Kies modellen uit de publieke API-lijst

Hardcode geen model alleen omdat het in een handmatige test werkte.

Gebruik API-modellen en Model API-referentie om te bevestigen:

• de publieke model-ID

• of het via de API beschikbaar is

• ondersteunde inputmodus

• prompt- en parameterverwachtingen

• of Files API vereist is

• creditgedrag en readiness-notities

Hier worden veel integraties schoner. Een model dat perfect is voor een handmatige Studio-test is niet automatisch het juiste eerste model voor een geautomatiseerde productflow.

Stap 3: Beslis of Files API onderdeel is van de eerste versie

Als het model vanuit tekstinput kan draaien, houd de eerste versie text-only.

Voeg Files API alleen toe wanneer de workflow echt referentiemedia nodig heeft.

Definieer dan:

• welke bestandstypen het product accepteert

• wie eigenaar is van de bestandscleanup

• wat er gebeurt wanneer upload faalt

• hoe de teruggegeven bestandsdata in modelparameters wordt doorgegeven

• of hetzelfde bestand moet worden hergebruikt of opnieuw geüpload

Zo voorkom je dat een fragiele bestandservaring verborgen zit achter een schoon uitziende generate-knop.

Stap 4: Dien één generatietaak in

Voor image-, video- en audiogeneratie is het normale patroon:

1. bereid de model-ID, prompt en ondersteunde params voor

2. voeg een idempotency key toe voor veilige retries

3. dien in via het generation endpoint

4. sla de publieke task ID op

5. poll status totdat de taak een terminal state bereikt

Gebruik Generatie aanmaken voor de requestvorm en Generatiestatus voor result handling.

Het product moet queued, processing, succeeded en failed behandelen als user-facing states. Laat gebruikers geen systeemdetails lezen of raden waarom een job traag is.

Stap 5: Gebruik Chat API voor chatmodellen

Chatmodellen moeten Chat API gebruiken, niet het generation endpoint.

Dat is belangrijk omdat chatwerk ander gedrag heeft:

• chat turns kunnen bij API-created sessions horen

• non-streaming en SSE streaming geven verschillende gebruikerservaringen

• afbeeldingsattachments gebruiken file IDs uit Files API

• creditsettlement volgt de chat turn in plaats van een normale async mediataak

Als je product een assistant-antwoord in de eigen interface nodig heeft, kan Chat API het juiste pad zijn. Als de gebruiker nog ideeën verkent, zijn Rivya Chat of Studio mogelijk beter.

Stap 6: Begin met polling en voeg daarna webhooks toe

Voor een eerste versie is polling makkelijker te begrijpen.

Als webhooks voor de deployment zijn ingeschakeld, voeg je API-webhooks toe wanneer:

• het product veel async jobs heeft

• wachtende clients niet direct moeten pollen

• downstreamsystemen ondertekende completion events nodig hebben

• retry- en duplicate-handling al is ontworpen

Webhook-ontvangers moeten saai en strikt zijn: verifieer de handtekening, accepteer duplicate-safe events, update één productrecord en log alleen wat veilig is om te loggen.

Stap 7: Maak credits zichtbaar in het product

Rivya API gebruikt dezelfde accountcredits als Studio.

Je integratie moet beslissen hoeveel daarvan wordt getoond. Minimaal moet het team weten:

• welk account eigenaar is van de API-key

• welke workflow credits kan verbruiken

• wat er gebeurt wanneer credits te laag zijn

• hoe failed generation states worden uitgelegd

• waar iemand naartoe moet voor credit- en billingvragen

Gebruik API-credits, de Rivya-gids voor credits en facturering en zo werken Rivya-credits, pakketten en abonnementen voor het portemonneemodel dat gebruikers zien.

Een kleine eerste versie

Een goede eerste versie is bewust beperkt.

Bijvoorbeeld:

1. één API-key

2. één geselecteerd beeldmodel

3. nog geen bestandsupload

4. één generation request

5. één statuspollingpad

6. één eenvoudige resultpreview in je product

7. één duidelijke creditfoutmelding

Die versie bewijst de verbinding voordat je meer bewegende delen toevoegt.

Een completere versie

Nadat de eerste versie werkt, kan een vollere workflow toevoegen:

• Files API voor referentiebeelden of video's

• modelspecifieke parametercontrols

• idempotency gekoppeld aan je productrecord

• ondertekende webhooks voor completion

• Chat API voor assistant turns

• een server-side event stream waar chat live output nodig heeft

• admin- of supportviews voor failed jobs

Elke toevoeging moet een echte productbehoefte beantwoorden. Als ze alleen de demo groter laat lijken, laat haar dan weg.

Veelgemaakte integratiefouten

Vermijd deze patronen:

• beginnen met elke API-feature tegelijk

• creditgebruik verbergen voor de accounteigenaar

• Studio-only aannames gebruiken in een API-flow

• file uploads als bijzaak behandelen

• generation requests opnieuw proberen zonder idempotency

• Chat API gebruiken voor jobs die async generation moeten zijn

• generation endpoints gebruiken voor chat turns

• volledige API-keys, webhook secrets of tijdelijke bestandsdetails loggen

De veiligste API-workflow is expliciet over ownership, state en failure handling.

Waar je hierna naartoe gaat

• Start bij Developers voor de publieke API-hub.

• Gebruik Rivya API-snelstart om de eerste request te draaien.

• Gebruik API-modellen voordat je model-ID's selecteert.

• Gebruik Files API alleen wanneer het model echt referentiemedia nodig heeft.

• Gebruik Chat API voor chat turns en streaming chat responses.

• Gebruik API-webhooks wanneer polling niet meer genoeg is.

• Als de workflow nog menselijke verkenning nodig heeft, lees Wanneer je Rivya API gebruikt in plaats van Studio voordat je hem automatiseert.