Bygg ett multimodalt arbetsflöde med Rivya API

En bra Rivya API-integration är inte bara en begäran till en modell.

De flesta verkliga produktarbetsflöden har en liten kedja: välj rätt modell, förbered indata, ladda upp referensfiler vid behov, skicka in ett jobb, följ status, hantera krediter och meddela produkten när resultatet är klart.

Den här artikeln visar planeringsformen. Använd Rivya API-snabbstart för den kortaste körbara vägen och använd API-dokumentationen för exakta begäransfält.

Börja med produktögonblicket

Innan du väljer endpoints beskriver du produktögonblicket i en mening.

Exempel:

• Skapa ett utkast till produktbild när en säljare skickar in en listningsbrief.
• Generera ett kort videokoncept efter att en kampanjansvarig har godkänt en stillbildsriktning.
• Skicka en chattur i ett internt researchverktyg och streama svaret tillbaka till användaren.
• Ladda upp en referensbild, skicka en stödd modellbegäran och meddela användaren när resultatet är klart.

Den meningen hindrar integrationen från att bli en lös samling API-anrop.

Kartlägg arbetsflödet innan du skriver kod

Använd den här tabellen innan du öppnar schemat för begäran.

Arbetsflödet ska vara tillräckligt tydligt för att varje API-område ska ha ett skäl att finnas.

Steg 1: Skapa en nyckel för integrationen

Skapa en API-nyckel för den specifika appen, miljön eller arbetsflödet som ska använda den.

Undvik att använda en nyckel för allt. Att namnge nycklar efter syfte gör senare granskning enklare:

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

Läs API-autentisering innan du lagrar nyckeln. Hela hemligheten visas en gång, så ditt team bör direkt spara den i rätt serverbaserad hemlighetslagring.

Steg 2: Välj modeller från den publika API-listan

Hårdkoda inte en modell bara för att den fungerade i ett manuellt test.

Använd API-modeller och modellreferensen för API för att bekräfta:

• publikt modell-ID
• om den är tillgänglig via API
• stödd indatametod
• förväntningar på prompt och parametrar
• om Files API krävs
• kreditbeteende och förberedelsenoteringar

Här blir många integrationer renare. En modell som är perfekt för ett manuellt Studio-test kanske inte är den bästa första modellen för ett automatiserat produktflöde.

Steg 3: Avgör om Files API ingår i första versionen

Om modellen kan köras från textindata håller du första versionen textbaserad.

Lägg bara till Files API när arbetsflödet verkligen behöver referensmedia.

När det gör det, definiera:

• vilka filtyper produkten accepterar
• vem som äger filrensningssteget
• vad som händer när uppladdningen misslyckas
• hur returnerad fildata skickas vidare till modellparametrar
• om samma fil ska återanvändas eller laddas upp igen

Det hindrar en skör filupplevelse från att döljas bakom en prydlig genereringsknapp.

Steg 4: Skicka ett genereringsjobb

För bild-, video- och ljudgenerering är det normala mönstret:

1. förbered modell-ID, prompt och stödda parametrar
2. lägg till en idempotensnyckel för säkra omförsök
3. skicka via genererings-endpointen
4. spara publikt uppgifts-ID
5. polla status tills uppgiften når ett slutläge

Använd Skapa generering för begäransformen och Genereringsstatus för resultathantering.

Produkten bör behandla queued, processing, succeeded och failed som användarsynliga tillstånd. Låt inte användare läsa systemdetaljer eller gissa varför ett jobb är långsamt.

Steg 5: Använd Chat API för chattmodeller

Chattmodeller ska använda Chat API, inte genererings-endpointen.

Det spelar roll eftersom chattarbete beter sig annorlunda:

• chatturer kan höra till API-skapade sessioner
• icke-streaming och SSE-streaming ger olika användarupplevelser
• bildbilagor använder fil-ID:n från Files API
• kreditavräkning följer chatturen snarare än ett vanligt asynkront mediajobb

Om din produkt behöver ett assistantsvar i sitt eget gränssnitt kan Chat API vara rätt väg. Om användaren fortfarande utforskar idéer kan Rivya Chat eller Studio passa bättre.

Steg 6: Börja med polling och lägg sedan till webhooks

För en första version är polling lättare att resonera om.

Lägg till API Webhooks när:

• produkten har många async-jobb
• väntande klienter inte bör polla direkt
• nedströms system behöver signerade sluthändelser
• omförsök och dubletthantering redan är utformade

Webhook-mottagare ska vara enkla och strikta: verifiera signaturen, acceptera dublettsäkra händelser, uppdatera en produktpost och logga bara sådant som är säkert att logga.

Steg 7: Gör credits synliga i produkten

Rivya API använder samma kontocredits som Studio.

Din integration bör avgöra hur mycket av det som ska visas. Som minimum bör teamet veta:

• vilket konto som äger API-nyckeln
• vilket arbetsflöde som kan förbruka credits
• vad som händer när credits är för låga
• hur misslyckade genereringstillstånd förklaras
• vart någon ska skickas med frågor om credits och fakturering

Använd API Credits, Credits och fakturering i Rivya och Hur du tänker kring Rivya credits, paket och planer för den användarsynliga plånboksmodellen.

En liten första version

En bra första version är avsiktligt begränsad.

Till exempel:

1. en API-nyckel
2. en vald bildmodell
3. ingen filuppladdning ännu
4. en genereringsbegäran
5. en väg för statuspolling
6. en enkel resultatförhandsvisning i din produkt
7. ett tydligt felmeddelande för credits

Den versionen bevisar kopplingen innan du lägger till fler rörliga delar.

En mer komplett version

När den första versionen fungerar kan ett fylligare arbetsflöde lägga till:

• Files API för referensbilder eller videor
• modellspecifika parameterkontroller
• idempotens kopplad till din produktpost
• signerade webhooks för slutförande
• Chat API för assistantturer
• en serverbaserad eventstream där chatt behöver liveutdata
• admin- eller supportvyer för misslyckade jobb

Varje tillägg ska svara på ett verkligt produktbehov. Om det bara får demon att se större ut, lämna det ute.

Vanliga integrationsmisstag

Undvik de här mönstren:

• att börja med varje API-funktion på en gång
• att dölja kreditanvändning för kontoägaren
• att använda Studio-exklusiva antaganden i ett API-flöde
• att behandla filuppladdningar som en eftertanke
• att försöka om genereringsbegäranden utan idempotens
• att använda Chat API för jobb som bör vara async-generering
• att använda genererings-endpoints för chatturer
• att logga fullständiga API-nycklar, webhook-hemligheter eller temporära fildetaljer

Det säkraste API-arbetsflödet är tydligt med ägarskap, tillstånd och felhantering.

Vart du går härnäst

• Börja från Utvecklare för den publika API-hubben.
• Använd Rivya API-snabbstart för att köra den första begäran.
• Använd API-modeller innan du väljer modell-ID:n.
• Använd Files API bara när modellen verkligen behöver referensmedia.
• Använd Chat API för chatturer och streamade chattsvar.
• Använd API Webhooks när polling inte längre räcker.
• Om arbetsflödet fortfarande behöver mänsklig utforskning, läs När du ska använda Rivya API i stället för Studio innan du automatiserar det.