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 inndataene, last opp referansefiler når det trengs, send inn en oppgave, følg status, håndter kreditter 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.

Arbeidsflyten nedenfor beskriver den implementerte Public API-kontrakten. Før du bygger, må du bekrefte at Public API-tilgang er aktivert for distribusjonen og kontoen, at den valgte modellen er API-klar, og at valgfrie funksjoner som webhooks faktisk er tilgjengelige.

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 umiddelbart lagre den i et egnet hemmelighetslager på serversiden.

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 API-modellreferansen for å bekrefte:

• offentlig modell-ID

• om den er tilgjengelig gjennom API-et

• støttet inputmodus

• forventninger til ledetekst og parametere

• om Fil-API er påkrevd

• kredittatferd og merknader om beredskap

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 Fil-API er del av første versjon

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

Legg til Fil-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. klargjør modell-ID, ledetekst og støttede parametere

2. legg til en idempotensnøkkel for trygge nye forsøk

3. send inn gjennom genereringsendpointet

4. lagre den offentlige oppgave-ID-en

5. kontroller status jevnlig til oppgaven når en endelig 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 Fil-API

• kredittoppgjøret følger chatrunden i stedet for en vanlig asynkron medieoppgave

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 statusspørring, legg deretter til webhooker

I en første versjon er regelmessig statusspørring enklere å planlegge.

Hvis webhooks er aktivert for distribusjonen, kan du legge til API Webhooks når:

• produktet har mange async jobber

• ventende clients ikke bør polle direkte

• nedstrømssystemer trenger signerte fullføringshendelser

• nye forsøk og håndtering av duplikater allerede er planlagt

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 kredittene 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 kreditter

• hva som skjer når kredittsaldoen er for lav

• hvordan feilede genereringstilstander forklares

• hvor brukeren skal sendes ved spørsmål om kreditter og fakturering

Bruk API-kreditter, Kreditter og fakturering i Rivya og Slik fungerer Rivya-kreditter, pakker og planer for kredittsaldoen brukeren ser.

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 feilmelding om kreditter

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:

• Fil-API for referansebilder eller videoer

• modellspesifikke parameterkontroller

• idempotency knyttet til produktrecorden din

• signerte webhooks ved fullføring når funksjonen er aktivert

• Chat API for assistentvendinger

• en hendelsesstrøm på serversiden når Chat trenger resultater i sanntid

• 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 kredittbruk 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 Fil-API bare når modellen virkelig trenger referansemedier.

• Bruk Chat API for chatvendinger og strømmende chatsvar.

• Bruk API-webhooker når statusspørring ikke lenger er nok og webhooktilgang er aktivert.

• Hvis arbeidsflyten fortsatt trenger menneskelig utforsking, les Når du bør bruke Rivya API i stedet for Studio før du automatiserer den.