Bygg en multimodal arbeidsflyt med Rivya API

En god Rivya API-integrasjon er ikke bare én forespørsel til én modell.

De fleste ekte produktarbeidsflyter har en liten kjede: velg riktig modell, forbered inputen, last opp referansefiler når det trengs, send inn en jobb, følg status, håndter credits og varsle produktet når resultatet er klart.

Denne artikkelen viser planleggingsformen. Bruk Rivya API-hurtigstart for den korteste kjørbare stien, og bruk API-dokumentasjonen for nøyaktige request-felt.

Start med produktøyeblikket

Før du velger endpoints, beskriv produktøyeblikket i én setning.

Eksempler:

• Lag et produktbildeutkast når en selger sender inn en oppføringsbrief.
• Generer et kort videokonsept etter at en kampanjeansvarlig godkjenner en stillbilderetning.
• Send en chatvending inne i et internt researchverktøy og strøm svaret tilbake til brukeren.
• Last opp et referansebilde, send inn en støttet modellforespørsel og varsle brukeren når resultatet er klart.

Den setningen hindrer integrasjonen i å bli en løs samling API-kall.

Kartlegg arbeidsflyten før du skriver kode

Bruk denne tabellen før du åpner request-skjemaet.

Arbeidsflyten bør være tydelig nok til at hvert API-område har en grunn til å finnes.

Steg 1: Opprett en nøkkel for integrasjonen

Opprett en API-nøkkel for den spesifikke appen, miljøet eller arbeidsflyten som skal bruke den.

Unngå å bruke én nøkkel til alt. Å navngi nøkler etter formål gjør senere gjennomgang enklere:

• production-image-workflow
• staging-video-tests
• internal-chat-assistant
• webhook-smoke-test

Les API-autentisering før du lagrer nøkkelen. Hele hemmeligheten vises én gang, så teamet bør lagre den i riktig server-side secret store med én gang.

Steg 2: Velg modeller fra den offentlige API-listen

Ikke hardkod en modell bare fordi den fungerte i en manuell test.

Bruk API-modeller og Model API Reference for å bekrefte:

• offentlig modell-ID
• om den er tilgjengelig gjennom API-et
• støttet inputmodus
• forventninger til prompt og parametere
• om Files API er påkrevd
• credit-atferd og beredskapsnotater

Det er her mange integrasjoner blir renere. En modell som er perfekt for en manuell Studio-test, er kanskje ikke riktig første modell for en automatisert produktflyt.

Steg 3: Bestem om Files API er del av første versjon

Hvis modellen kan kjøre fra tekstinput, hold første versjon tekst-only.

Legg til Files API bare når arbeidsflyten virkelig trenger referansemedier.

Når den gjør det, definer:

• hvilke filtyper produktet aksepterer
• hvem som eier filoppryddingssteget
• hva som skjer når opplasting feiler
• hvordan returnerte fildata sendes inn i modellparametere
• om samme fil bør gjenbrukes eller lastes opp igjen

Dette hindrer at en skjør filopplevelse skjules bak en ren generer-knapp.

Steg 4: Send inn én genereringsjobb

For bilde-, video- og lydgenerering er normalmønsteret:

1. forbered modell-ID, prompt og støttede params
2. legg til en idempotency key for trygge retries
3. send inn gjennom genereringsendpointet
4. lagre offentlig task ID
5. poll status til tasken når en terminal tilstand

Bruk Opprett generering for request-formen og Genereringsstatus for resulthåndtering.

Produktet bør behandle queued, processing, succeeded og failed som brukerrettede tilstander. Ikke få brukerne til å lese systemdetaljer eller gjette hvorfor en jobb er treg.

Steg 5: Bruk Chat API for chatmodeller

Chatmodeller bør bruke Chat API, ikke genereringsendpointet.

Det betyr noe fordi chatarbeid oppfører seg annerledes:

• chatvendinger kan høre til API-opprettede sessions
• ikke-strømming og SSE-strømming gir ulike brukeropplevelser
• bildevedlegg bruker fil-ID-er fra Files API
• credit-oppgjør følger chatvendingen heller enn en vanlig async mediatask

Hvis produktet ditt trenger et assistentsvar inne i sitt eget grensesnitt, kan Chat API være riktig sti. Hvis brukeren fortsatt utforsker ideer, kan Rivya Chat eller Studio være bedre.

Steg 6: Start med polling, legg deretter til webhooks

For en første versjon er polling enklere å resonnere om.

Legg til API Webhooks når:

• produktet har mange async jobber
• ventende clients ikke bør polle direkte
• nedstrømssystemer trenger signerte fullføringshendelser
• retry- og duplikathåndtering allerede er designet

Webhook-mottakere bør være kjedelige og strenge: verifiser signaturen, aksepter duplikatsikre hendelser, oppdater én produktrecord og logg bare det som er trygt å logge.

Steg 7: Gjør credits synlige i produktet

Rivya API bruker de samme kontocredits som Studio.

Integrasjonen bør bestemme hvor mye av dette som skal vises. Som minimum bør teamet vite:

• hvilken konto som eier API-nøkkelen
• hvilken arbeidsflyt som kan bruke credits
• hva som skjer når credits er for lave
• hvordan feilede genereringstilstander forklares
• hvor noen skal sendes for spørsmål om credits og fakturering

Bruk API Credits, Credits og fakturering i Rivya og Slik tenker du om Rivya credits, pakker og planer for den brukerrettede wallet-modellen.

En liten første versjon

En god første versjon er med vilje begrenset.

For eksempel:

1. én API-nøkkel
2. én valgt bildemodell
3. ingen filopplasting ennå
4. én genereringsforespørsel
5. én statuspollingsti
6. én enkel resultatpreview i produktet ditt
7. én tydelig credit-feilmelding

Den versjonen beviser forbindelsen før du legger til flere bevegelige deler.

En mer komplett versjon

Etter at første versjon fungerer, kan en fyldigere arbeidsflyt legge til:

• Files API for referansebilder eller videoer
• modellspesifikke parameterkontroller
• idempotency knyttet til produktrecorden din
• signerte webhooks for fullføring
• Chat API for assistentvendinger
• en server-side event stream der chat trenger live output
• admin- eller supportvisninger for feilede jobber

Hvert tillegg bør svare på et ekte produktbehov. Hvis det bare får demoen til å se større ut, la det ligge.

Vanlige integrasjonsfeil

Unngå disse mønstrene:

• å starte med hver API-funksjon samtidig
• å skjule credit-bruk for kontoeieren
• å bruke Studio-only-antakelser i en API-flyt
• å behandle filopplastinger som en ettertanke
• å retrye genereringsforespørsler uten idempotency
• å bruke Chat API for jobber som bør være async generering
• å bruke genereringsendpoints for chatvendinger
• å logge fulle API-nøkler, webhook secrets eller midlertidige fildetaljer

Den tryggeste API-arbeidsflyten er eksplisitt om eierskap, tilstand og feilhåndtering.

Hvor du går videre

• Start fra Developers for den offentlige API-huben.
• Bruk Rivya API-hurtigstart for å kjøre den første forespørselen.
• Bruk API-modeller før du velger modell-ID-er.
• Bruk Files API bare når modellen virkelig trenger referansemedier.
• Bruk Chat API for chatvendinger og strømmende chatsvar.
• Bruk API Webhooks når polling ikke lenger er nok.
• Hvis arbeidsflyten fortsatt trenger menneskelig utforsking, les Når du bør bruke Rivya API i stedet for Studio før du automatiserer den.