Een goede Rivya API-integratie is niet zomaar één request naar één model.

De meeste echte productworkflows hebben een kleine keten: kies het juiste model, bereid de input voor, upload waar nodig referentiebestanden, dien een job in, volg de status, verwerk credits en notify het product wanneer het resultaat klaar is.

Dit artikel laat de planningsvorm zien. Gebruik Rivya API-snelstart voor het kortste uitvoerbare pad en gebruik de API-docs voor exacte requestvelden.

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.

Workflowstap	Productvraag	API-gebied
Accounttoegang	Welk Rivya-account is eigenaar van het gebruik?	API-authenticatie
Modelkeuze	Welke publieke model-ID past bij deze job?	API-modellen
Referentie-input	Heeft het model geüploade media nodig?	Files API
Generatie	Is dit een async image-, video- of audiojob?	Generatie aanmaken
Chat	Is dit een chatmodel-turn in plaats van een generation job?	Chat API
Status	Hoe weet het product dat het resultaat klaar is?	Generatiestatus
Afrondingsevent	Moet een ander systeem een ondertekende callback ontvangen?	API-webhooks
Credits	Hoe begrijpt het team de kosten?	API-credits

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:

bereid de model-ID, prompt en ondersteunde params voor
voeg een idempotency key toe voor veilige retries
dien in via het generation endpoint
sla de publieke task ID op
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: Start met polling en voeg daarna webhooks toe

Voor een eerste versie is polling makkelijker te begrijpen.

Voeg 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, Rivya gids voor credits en billing en Zo denk je over Rivya-credits, packs en plans voor het user-facing walletmodel.

Een kleine eerste versie

Een goede eerste versie is bewust beperkt.

Bijvoorbeeld:

één API-key
één geselecteerd beeldmodel
nog geen bestandsupload
één generation request
één statuspollingpad
één eenvoudige resultpreview in je product
éé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.

Bouw een multimodale workflow met de Rivya API