Byg en multimodal arbejdsgang med Rivya API

En god integration med Rivya API er ikke blot én anmodning til én model.

De fleste reelle produktarbejdsgange består af en kort kæde: Vælg den rigtige model, forbered inputtet, upload om nødvendigt referencefiler, indsend en opgave, følg dens status, håndter kreditterne, og giv produktet besked, når resultatet er klar.

Denne artikel viser, hvordan forløbet kan planlægges. Brug Hurtig start med Rivya API til den korteste kørbare vej, og brug API-dokumentationen til de præcise felter i anmodningen.

Arbejdsgangen nedenfor beskriver den implementerede Public API-kontrakt. Før du bygger, skal du bekræfte, at Public API-adgang er aktiveret for installationen og kontoen, at den valgte model er API-klar, og at valgfrie funktioner som webhooks faktisk er tilgængelige.

Start med produktøjeblikket

Før du vælger slutpunkter, skal du beskrive produktøjeblikket i én sætning.

Eksempler:

• Opret et udkast til et produktbillede, når en sælger indsender en beskrivelse til en vareannonce.

• Generér et kort videokoncept, når en kampagneansvarlig har godkendt retningen for et stillbillede.

• Send en chatbesked i et internt researchværktøj, og stream svaret tilbage til brugeren.

• Upload et referencebillede, send en anmodning til en understøttet model, og giv brugeren besked, når resultatet er klar.

Den sætning forhindrer integrationen i at blive en løs samling API-kald.

Kortlæg arbejdsgangen, før du skriver kode

Brug denne tabel, før du åbner anmodningsskemaet.

Arbejdsgangen skal være tydelig nok til, at hvert API-område har en grund til at være med.

Trin 1: Opret en nøgle til integrationen

Opret en API-nøgle til den konkrete app, det miljø eller den arbejdsgang, der skal bruge den.

Undgå at bruge én nøgle til alt. Navngivning efter formål gør den senere gennemgang lettere:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

Læs API-godkendelse, før du gemmer nøglen. Den fulde hemmelighed vises én gang, så teamet bør straks gemme den i et egnet hemmelighedslager på serversiden.

Trin 2: Vælg modeller fra den offentlige API-liste

Fastkod ikke en model, blot fordi den virkede i en manuel test.

Brug API-modeller og API-reference for modeller til at bekræfte:

• det offentlige model-ID

• om den er tilgængelig gennem API'et

• understøttet inputtype

• krav til instruktion og parametre

• om Fil-API-et er påkrævet

• kreditadfærd og bemærkninger om driftsklarhed

Det er her, mange integrationer bliver enklere. En model, der er perfekt til en manuel test i Studio, er ikke nødvendigvis den rigtige første model til et automatiseret produktforløb.

Trin 3: Beslut, om Fil-API-et skal med i første version

Hvis modellen kan køre fra tekstinput, så lad den første version være rent tekstbaseret.

Tilføj kun Fil-API-et, når arbejdsgangen virkelig har brug for referencemedier.

Når det gør, skal du definere:

• hvilke filtyper produktet accepterer

• hvem der ejer filoprydningstrinnet

• hvad der sker, når upload fejler

• hvordan de returnerede fildata sendes ind i modelparametre

• om den samme fil skal genbruges eller uploades igen

Det forhindrer en skrøbelig filoplevelse i at blive skjult bag en generér-knap, der ser ren ud.

Trin 4: Indsend én genereringsopgave

Ved billed-, video- og lydgenerering er det normale mønster:

1. forbered model-ID, instruktion og understøttede parametre

2. tilføj en idempotensnøgle, så gentagne forsøg er sikre

3. indsend gennem genereringsslutpunktet

4. gem det offentlige opgave-ID

5. hent status med jævne mellemrum, indtil opgaven når en sluttilstand

Brug Opret generering til anmodningsformatet og Genereringsstatus til håndtering af resultatet.

Produktet bør behandle queued, processing, succeeded og failed som tilstande, brugeren kan forstå. Lad ikke brugere læse systemdetaljer eller gætte, hvorfor en opgave er langsom.

Trin 5: Brug Chat API til chatmodeller

Chatmodeller bør bruge Chat API, ikke genereringsslutpunktet.

Det betyder noget, fordi chatarbejde har anden adfærd:

• chatbeskeder kan tilhøre sessioner, der er oprettet via API-et

• svar med og uden SSE-streaming giver forskellige brugeroplevelser

• billedvedhæftninger bruger fil-ID'er fra Fil-API-et

• kreditafregningen følger chatbeskeden i stedet for en almindelig asynkron medieopgave

Hvis dit produkt har brug for et svar fra assistenten i sin egen grænseflade, kan Chat API være den rigtige vej. Hvis brugeren stadig udforsker idéer, kan Rivya Chat eller Studio være bedre.

Trin 6: Start med statusforespørgsler, og tilføj derefter webhooks

I en første version er regelmæssige statusforespørgsler lettere at overskue.

Hvis webhooks er aktiveret for installationen, kan du tilføje API-webhooks, når:

• produktet har mange asynkrone opgaver

• ventende klienter ikke bør hente status direkte

• efterfølgende systemer har brug for signerede fuldførelseshændelser

• håndtering af gentagne forsøg og dubletter allerede er designet

Webhookmodtagere bør være enkle og strikse: Kontrollér signaturen, acceptér dubletsikre hændelser, opdatér én produktpost, og log kun det, der er sikkert at logge.

Trin 7: Gør kreditterne synlige i produktet

Rivya API bruger de samme kontokreditter som Studio.

Din integration bør beslutte, hvor meget af det der skal vises. Som minimum bør teamet vide:

• hvilken konto der ejer API-nøglen

• hvilken arbejdsgang der kan bruge kreditter

• hvad der sker, når kreditsaldoen er for lav

• hvordan mislykkede genereringstilstande forklares

• hvor brugeren skal hen med spørgsmål om kreditter og fakturering

Brug API-kreditter, Kreditter og fakturering i Rivya og Sådan fungerer Rivyas kreditter, pakker og abonnementer til den kreditmodel, brugeren møder.

En lille første version

En god første version er bevidst begrænset.

For eksempel:

1. én API-nøgle

2. én valgt billedmodel

3. ingen filupload endnu

4. én genereringsanmodning

5. én vej til at hente status

6. én enkel forhåndsvisning af resultatet i dit produkt

7. én klar kreditfejlbesked

Den version beviser forbindelsen, før du tilføjer flere bevægelige dele.

En mere komplet version

Når første version virker, kan en mere komplet arbejdsgang tilføje:

• Fil-API-et til referencebilleder eller videoer

• modelspecifikke parameterkontroller

• idempotens knyttet til produktposten

• signerede webhooks ved fuldførelse, når funktionen er aktiveret

• Chat API til assistentbeskeder

• en hændelsesstrøm fra serveren, når chatten skal vise svar løbende

• administrator- eller supportvisninger til mislykkede opgaver

Hver tilføjelse bør svare på et reelt produktbehov. Hvis den kun får demoen til at se større ud, så lad den blive ude.

Almindelige integrationsfejl

Undgå disse mønstre:

• at begynde med alle API-funktioner på én gang

• at skjule kreditforbrug for kontoejeren

• at bruge antagelser, der kun gælder Studio, i et API-forløb

• at behandle filuploads som en eftertanke

• at gentage genereringsanmodninger uden idempotens

• at bruge Chat API til opgaver, der bør være asynkron generering

• at bruge genereringsslutpunkter til chatbeskeder

• at logge hele API-nøgler, webhookhemmeligheder eller midlertidige fildetaljer

Den sikreste API-arbejdsgang er tydelig om ejerskab, tilstand og fejlhåndtering.

Hvor du går videre

• Start på Udviklersiden for at få overblik over det offentlige API.

• Brug Hurtig start med Rivya API til at køre den første anmodning.

• Brug API-modeller, før du vælger model-ID'er.

• Brug kun Fil-API-et, når modellen virkelig har brug for referencemedier.

• Brug Chat API til chatbeskeder og streamede chatsvar.

• Brug API-webhooks, når regelmæssige statusforespørgsler ikke længere er nok, og webhookadgang er aktiveret.

• Hvis arbejdsgangen stadig kræver menneskelig udforskning, så læs Hvornår du skal bruge Rivya API i stedet for Studio, før du automatiserer den.