Construiește un flux de lucru multimodal cu API-ul Rivya

O integrare reușită cu API-ul Rivya nu se rezumă la trimiterea unei cereri către un singur model.

Majoritatea funcțiilor dintr-un produs real urmează un lanț scurt: alegi modelul potrivit, pregătești datele de intrare, încarci fișiere de referință atunci când sunt necesare, trimiți o sarcină, urmărești starea acesteia, gestionezi creditele și anunți produsul când rezultatul este gata.

Acest articol prezintă modul de planificare a întregului proces. Folosește Pornirea rapidă pentru API-ul Rivya pentru cea mai scurtă cale către o cerere funcțională și consultă documentația API pentru câmpurile exacte.

Fluxul de mai jos descrie contractul Public API implementat. Înainte de dezvoltare, confirmă că accesul Public API este activ pentru implementare și pentru cont, că modelul ales este pregătit pentru API și că funcțiile opționale, precum webhook-urile, sunt disponibile efectiv.

Începe cu momentul din produs

Înainte să alegi punctele finale, descrie într-o singură propoziție momentul în care funcția este folosită în produs.

Exemple:

• Creează o schiță a imaginii de produs când un vânzător trimite detaliile unei listări.

• Generează un concept video scurt după ce managerul campaniei aprobă o direcție vizuală statică.

• Trimite un mesaj dintr-un instrument intern de cercetare și transmite răspunsul în flux către utilizator.

• Încarcă o imagine de referință, trimite o cerere către un model acceptat și anunță utilizatorul când rezultatul este gata.

Această propoziție împiedică integrarea să devină o colecție fără legătură de apeluri API.

Planifică fluxul de lucru înainte să scrii cod

Folosește acest tabel înainte să deschizi schemă cererii.

Fluxul ar trebui să fie suficient de clar încât fiecare zonă API să aibă un rol justificat.

Pasul 1: creează o cheie pentru integrare

Creează o cheie API pentru aplicația, mediul sau fluxul de lucru care o va folosi.

Evită să folosești aceeași cheie pentru toate situațiile. Numele care descriu scopul cheii simplifică verificările ulterioare:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

Citește Autentificare API înainte să stochezi cheia. Secretul complet este afișat o singură dată, așa că echipa trebuie să îl salveze imediat în sistemul de gestionare a secretelor de pe server.

Pasul 2: alege modele din lista publică API

Nu înscrie definitiv un model în cod doar pentru că a funcționat într-un test manual.

Folosește Modele API și Referința API pentru modele pentru a confirma:

• identificatorul public al modelului

• dacă modelul este disponibil prin API

• modul de intrare acceptat

• cerințele pentru instrucțiuni și parametri

• dacă este necesar Files API

• comportamentul creditelor și informațiile privind disponibilitatea operațională

În acest punct, multe integrări devin mai bine definite. Un model perfect pentru un test manual în Studio nu este neapărat primul model potrivit pentru un proces automatizat din produs.

Pasul 3: decide dacă Files API intră în prima versiune

Dacă modelul poate rula doar cu text, păstrează prima versiune bazată exclusiv pe text.

Adaugă Files API numai atunci când fluxul de lucru chiar necesită materiale media de referință.

În acest caz, stabilește:

• ce tipuri de fișiere acceptă produsul

• cine răspunde de pregătirea fișierelor

• ce se întâmplă dacă încărcarea eșuează

• cum sunt transmise datele fișierului returnat în parametrii modelului

• dacă același fișier trebuie reutilizat sau încărcat din nou

Astfel, o experiență fragilă de gestionare a fișierelor nu rămâne ascunsă în spatele unui buton de generare cu aspect simplu.

Pasul 4: trimite o singură sarcină de generare

Pentru generarea de imagini, clipuri video și materiale audio, succesiunea obișnuită este:

1. pregătește identificatorul modelului, instrucțiunea și parametrii acceptați

2. adaugă o cheie de idempotență pentru reîncercări sigure

3. trimite cererea către punctul final de generare

4. salvează identificatorul public al sarcinii

5. interoghează starea până când sarcina ajunge într-o stare finală

Folosește Crearea unei generări pentru structura cererii și Starea generării pentru gestionarea rezultatului.

Produsul ar trebui să prezinte queued, processing, succeeded și failed ca stări ușor de înțeles pentru utilizator. Nu îl obliga să citească detalii de sistem sau să ghicească de ce o sarcină durează mult.

Pasul 5: folosește Chat API pentru modelele conversaționale

Modelele conversaționale trebuie apelate prin Chat API, nu prin punctul final de generare.

Distincția contează, deoarece conversațiile au un comportament diferit:

• mesajele pot aparține unor sesiuni create prin API

• răspunsurile complete și transmiterea în flux prin SSE oferă experiențe diferite

• imaginile atașate folosesc identificatori de fișier din Files API

• decontarea creditelor urmează schimbul de mesaje, nu o sarcină media asincronă obișnuită

Dacă produsul trebuie să afișeze răspunsul unui asistent în propria interfață, Chat API poate fi alegerea potrivită. Dacă utilizatorul încă explorează idei, Rivya Chat sau Studio poate fi mai potrivit.

Pasul 6: începe cu interogarea periodică, apoi adaugă webhook-uri

În prima versiune, interogarea periodică este mai ușor de înțeles și de verificat.

Dacă webhook-urile sunt activate pentru implementare, adaugă API Webhooks atunci când:

• produsul gestionează multe sarcini asincrone

• clienții care așteaptă nu ar trebui să interogheze direct starea

• sistemele din aval au nevoie de evenimente de finalizare semnate

• gestionarea reîncercărilor și a evenimentelor duplicate este deja proiectată

Componenta care primește webhook-urile trebuie să rămână simplă și strictă: verifică semnătura, acceptă în siguranță evenimentele duplicate, actualizează o singură înregistrare din produs și păstrează în jurnale doar informații sigure.

Pasul 7: afișează creditele în produs

API-ul Rivya folosește aceleași credite de cont ca Studio.

Integrarea trebuie să stabilească cât de multe informații afișează utilizatorului. Echipa trebuie să știe cel puțin:

• ce cont deține cheia API

• ce flux de lucru poate consuma credite

• ce se întâmplă când creditele sunt insuficiente

• cum sunt explicate stările de generare eșuată

• unde sunt îndrumați utilizatorii pentru întrebări despre credite și facturare

Folosește Credite API, Credite și facturare în Rivya și Cum să înțelegi creditele, pachetele și planurile Rivya pentru modelul de portofel prezentat utilizatorului.

O primă versiune restrânsă

O primă versiune bună este limitată în mod intenționat.

De exemplu:

1. o singură cheie API

2. un singur model de imagine selectat

3. fără încărcare de fișiere deocamdată

4. o singură cerere de generare

5. o rută simplă pentru interogarea periodică a stării

6. o previzualizare simplă a rezultatului în produs

7. un mesaj clar atunci când creditele sunt insuficiente

Această versiune dovedește că legătura funcționează înainte să adaugi mai multe componente.

O versiune mai completă

După ce prima versiune funcționează, un flux de lucru mai complet poate include:

• Files API pentru imagini sau clipuri video de referință

• opțiuni pentru parametrii specifici modelului

• idempotență asociată înregistrării corespunzătoare din produs

• webhook-uri semnate pentru finalizare, atunci când funcția este activă

• Chat API pentru conversațiile cu asistentul

• un flux de evenimente de pe server atunci când conversația necesită rezultate în timp real

• ecrane de administrare sau asistență pentru sarcinile eșuate

Fiecare adăugare trebuie să răspundă unei nevoi reale a produsului. Dacă doar face demonstrația să pară mai complexă, nu o include.

Greșeli frecvente de integrare

Evită aceste abordări:

• includerea tuturor funcțiilor API încă din prima versiune

• ascunderea consumului de credite față de proprietarul contului

• folosirea în API a unor presupuneri valabile numai în Studio

• tratarea încărcării fișierelor ca detaliu de ultim moment

• retrimiterea cererilor de generare fără idempotență

• folosirea Chat API pentru sarcini care ar trebui să fie generări asincrone

• folosirea punctelor finale de generare pentru conversații

• înscrierea în jurnale a cheilor API complete, a secretelor webhook sau a detaliilor temporare despre fișiere

Cel mai sigur flux de lucru API definește clar responsabilitatea, starea și gestionarea erorilor.

Unde să mergi mai departe

• Începe de la Developers, centrul public dedicat API-ului.

• Folosește Pornirea rapidă pentru API-ul Rivya pentru a rula prima cerere.

• Consultă Modele API înainte să alegi identificatorii modelelor.

• Folosește Files API numai când modelul are într-adevăr nevoie de materiale media de referință.

• Folosește Chat API pentru conversații și răspunsuri transmise în flux.

• Folosește API Webhooks când interogarea periodică nu mai este suficientă și accesul la webhook-uri este activ.

• Dacă fluxul de lucru are încă nevoie de explorare umană, citește Când să folosești API-ul Rivya în locul Studio înainte să îl automatizezi.