Construieste un workflow multimodal cu Rivya API

O integrare Rivya API buna nu este doar o cerere catre un singur model.

Cele mai multe workflowuri reale de produs au un lant mic: alege modelul potrivit, pregateste inputul, incarca fisiere de referinta cand este nevoie, trimite un job, urmareste statusul, gestioneaza creditele si notifica produsul cand rezultatul este gata.

Acest articol arata forma de planificare. Foloseste Pornire rapida Rivya API pentru cea mai scurta ruta rulabila si foloseste documentatia API pentru campurile exacte ale cererii.

Incepe cu momentul de produs

Inainte sa alegi endpointuri, descrie momentul de produs intr-o singura propozitie.

Exemple:

• Creeaza o schita de imagine de produs cand un vanzator trimite un brief de listare.
• Genereaza un concept video scurt dupa ce un manager de campanie aproba o directie statica.
• Trimite un schimb de chat intr-un instrument intern de cercetare si transmite raspunsul inapoi catre utilizator.
• Incarca o imagine de referinta, trimite o cerere catre un model acceptat si notifica utilizatorul cand rezultatul este gata.

Acea propozitie impiedica integrarea sa devina o colectie libera de apeluri API.

Mapeaza workflowul inainte sa scrii cod

Foloseste acest tabel inainte sa deschizi schema cererii.

Workflowul ar trebui sa fie destul de clar incat fiecare zona API sa aiba un motiv sa existe.

Pasul 1: creeaza o cheie pentru integrare

Creeaza o cheie API pentru aplicatia, mediul sau workflowul specific care o va folosi.

Evita sa folosesti o singura cheie pentru orice. Numirea cheilor dupa scop face revizuirea ulterioara mai usoara:

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

Citeste Autentificare API inainte sa stochezi cheia. Secretul complet este afisat o singura data, asa ca echipa ta ar trebui sa il salveze imediat in store-ul server-side de secrete potrivit.

Pasul 2: alege modele din lista publica API

Nu hard-coda un model doar pentru ca a functionat intr-un test manual.

Foloseste Modele API si Referinta API pentru modele ca sa confirmi:

• ID-ul public al modelului
• daca este disponibil prin API
• modul de input acceptat
• asteptarile pentru prompt si parametri
• daca Files API este necesar
• comportamentul de credite si notele de readiness

Aici multe integrari devin mai curate. Un model perfect pentru un test manual in Studio poate sa nu fie primul model potrivit pentru un flux automatizat de produs.

Pasul 3: decide daca Files API face parte din prima versiune

Daca modelul poate rula din input text, pastreaza prima versiune doar text.

Adauga Files API doar atunci cand workflowul are cu adevarat nevoie de media de referinta.

Cand are nevoie, defineste:

• ce tipuri de fisiere accepta produsul
• cine detine pasul de curatare a fisierelor
• ce se intampla cand uploadul esueaza
• cum datele de fisier returnate sunt transmise in parametrii modelului
• daca acelasi fisier ar trebui refolosit sau incarcat din nou

Asta impiedica o experienta fragila cu fisiere sa fie ascunsa in spatele unui buton de generare care arata curat.

Pasul 4: trimite un singur job de generare

Pentru generare de imagini, video si audio, modelul normal este:

1. pregateste ID-ul modelului, promptul si parametrii acceptati
2. adauga o cheie de idempotenta pentru retry-uri sigure
3. trimite prin endpointul de generare
4. salveaza ID-ul public al taskului
5. interogheaza statusul pana cand taskul ajunge intr-o stare terminala

Foloseste Creeaza o generare pentru forma cererii si Statusul generarii pentru gestionarea rezultatului.

Produsul ar trebui sa trateze queued, processing, succeeded si failed ca stari vizibile pentru utilizator. Nu-i face pe utilizatori sa citeasca detalii de sistem sau sa ghiceasca de ce un job este lent.

Pasul 5: foloseste Chat API pentru modele de chat

Modelele de chat ar trebui sa foloseasca Chat API, nu endpointul de generare.

Conteaza, deoarece munca de chat are comportament diferit:

• schimburile de chat pot apartine unor sesiuni create prin API
• streamingul non-streaming si SSE au experiente de utilizare diferite
• atasamentele de imagine folosesc ID-uri de fisier din Files API
• decontarea creditelor urmeaza schimbul de chat, nu un task media async normal

Daca produsul tau are nevoie de un raspuns de asistent in propria interfata, Chat API poate fi ruta potrivita. Daca utilizatorul inca exploreaza idei, Rivya Chat sau Studio poate fi mai bun.

Pasul 6: incepe cu polling, apoi adauga webhooks

Pentru o prima versiune, pollingul este mai usor de inteles.

Adauga API Webhooks cand:

• produsul are multe joburi async
• clientii care asteapta nu ar trebui sa interogheze direct
• sistemele downstream au nevoie de evenimente de finalizare semnate
• gestionarea retry-urilor si duplicatelor este deja proiectata

Receiver-ele webhook ar trebui sa fie banale si stricte: verifica semnatura, accepta evenimente duplicate-safe, actualizeaza o singura inregistrare de produs si logheaza doar ce este sigur de logat.

Pasul 7: fa creditele vizibile in produs

Rivya API foloseste aceleasi credite de cont ca Studio.

Integrarea ta ar trebui sa decida cat din asta sa arate. Cel putin, echipa ar trebui sa stie:

• ce cont detine cheia API
• ce workflow poate consuma credite
• ce se intampla cand creditele sunt prea mici
• cum sunt explicate starile de generare esuate
• unde sa trimita pe cineva pentru intrebari despre credite si facturare

Foloseste Credite API, Credite si facturare in Rivya si Cum sa gandesti creditele, pachetele si planurile Rivya pentru modelul de portofel vizibil utilizatorului.

O prima versiune mica

O prima versiune buna este limitata intentionat.

De exemplu:

1. o cheie API
2. un model de imagine selectat
3. fara upload de fisiere inca
4. o cerere de generare
5. o ruta simpla de polling pentru status
6. o previzualizare simpla a rezultatului in produsul tau
7. un mesaj clar de eroare pentru credite

Acea versiune dovedeste conexiunea inainte sa adauge mai multe piese mobile.

O versiune mai completa

Dupa ce prima versiune functioneaza, un workflow mai complet poate adauga:

• Files API pentru imagini sau video-uri de referinta
• controale de parametri specifice modelului
• idempotenta legata de inregistrarea din produsul tau
• webhooks semnate pentru finalizare
• Chat API pentru schimburi cu asistentul
• un stream de evenimente server-side acolo unde chatul are nevoie de output live
• viewuri de admin sau support pentru joburi esuate

Fiecare adaugare ar trebui sa raspunda unei nevoi reale de produs. Daca doar face demo-ul sa para mai mare, las-o afara.

Greseli comune de integrare

Evita aceste tipare:

• sa incepi cu fiecare functie API deodata
• sa ascunzi utilizarea creditelor de proprietarul contului
• sa folosesti presupuneri doar din Studio intr-un flux API
• sa tratezi uploadurile de fisiere ca pe un gand ulterior
• sa retrimiti cereri de generare fara idempotenta
• sa folosesti Chat API pentru joburi care ar trebui sa fie generare async
• sa folosesti endpointuri de generare pentru schimburi de chat
• sa loghezi chei API complete, secrete webhook sau detalii temporare de fisiere

Cel mai sigur workflow API este explicit despre proprietate, stare si gestionarea esecurilor.

Unde sa mergi mai departe

• Incepe de la Developers pentru hubul API public.
• Foloseste Pornire rapida Rivya API ca sa rulezi prima cerere.
• Foloseste Modele API inainte sa selectezi ID-uri de model.
• Foloseste Files API doar cand modelul chiar are nevoie de media de referinta.
• Foloseste Chat API pentru schimburi de chat si raspunsuri de chat in streaming.
• Foloseste API Webhooks cand pollingul nu mai este suficient.
• Daca workflowul inca are nevoie de explorare umana, citeste Cand sa folosesti Rivya API in loc de Studio inainte sa il automatizezi.