Multimodális munkafolyamat építése a Rivya API-val

Egy jó Rivya API-integráció nem csak egyetlen kérés egyetlen modellhez.

A legtöbb valódi termékfolyamat egy kisebb láncból áll: ki kell választani a megfelelő modellt, elő kell készíteni a bemenetet, szükség esetén referenciafájlokat kell feltölteni, el kell indítani a feladatot, figyelni kell az állapotot, kezelni kell a krediteket, és értesíteni kell a terméket, amikor az eredmény elkészült.

Ez a cikk a tervezési formát mutatja meg. A legrövidebb futtatható útvonalhoz használja a Rivya API gyorskezdés útmutatót, a pontos kérésmezőkhöz pedig az API-dokumentációt.

Kezdje a termékpillanattal

Mielőtt végpontokat választana, írja le egy mondatban a termékpillanatot.

Példák:

• Termékkép-vázlat létrehozása, amikor egy eladó beküld egy listing briefet.
• Rövid videókoncepció generálása, miután egy kampánymenedzser jóváhagyott egy állóképes irányt.
• Chatforduló küldése egy belső kutatási eszközben, majd a válasz streamelése vissza a felhasználónak.
• Referencia kép feltöltése, támogatott modellkérés elküldése, majd a felhasználó értesítése, amikor az eredmény elkészült.

Ez a mondat megakadályozza, hogy az integráció laza API-hívások gyűjteményévé váljon.

Térképezze fel a munkafolyamatot, mielőtt kódot ír

Használja ezt a táblázatot, mielőtt megnyitná a kérési sémát.

A munkafolyamatnak elég világosnak kell lennie ahhoz, hogy minden API-területnek legyen oka létezni.

1. lépés: Hozzon létre kulcsot az integrációhoz

Hozzon létre API-kulcsot ahhoz a konkrét alkalmazáshoz, környezethez vagy munkafolyamathoz, amely használni fogja.

Ne használjon egyetlen kulcsot mindenre. Ha a kulcsokat cél szerint nevezi el, később könnyebb lesz az ellenőrzés:

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

Olvassa el az API-hitelesítés dokumentációt, mielőtt eltárolja a kulcsot. A teljes titok csak egyszer jelenik meg, ezért a csapatának azonnal a megfelelő szerveroldali titoktárba kell mentenie.

2. lépés: Válasszon modelleket a nyilvános API-listából

Ne égesse be a modellt csak azért, mert egy kézi tesztben működött.

Az API modellek és a Modell API referencia alapján erősítse meg:

• a nyilvános modellazonosítót
• hogy elérhető-e az API-n keresztül
• a támogatott bemeneti módot
• a prompttal és paraméterekkel kapcsolatos elvárásokat
• hogy szükséges-e a Files API
• a kreditviselkedést és a készenléti megjegyzéseket

Itt sok integráció tisztábbá válik. Egy modell, amely kézi Studio-teszthez tökéletes, nem biztos, hogy a legjobb első modell egy automatizált termékfolyamathoz.

3. lépés: Döntse el, része-e a Files API az első verziónak

Ha a modell szöveges bemenetről is futtatható, tartsa az első verziót csak szövegesnek.

A Files API használatát csak akkor adja hozzá, amikor a munkafolyamatnak valóban szüksége van referenciamédiára.

Amikor szüksége van rá, határozza meg:

• milyen fájltípusokat fogad el a termék
• ki felel a fájltakarítási lépésért
• mi történik, ha a feltöltés sikertelen
• hogyan kerül a visszakapott fájladat a modellparaméterekbe
• ugyanazt a fájlt újra kell-e használni, vagy ismét fel kell tölteni

Így a törékeny fájlélmény nem bújik el egy tisztának tűnő generálás gomb mögött.

4. lépés: Küldjön be egy generálási feladatot

Kép-, videó- és hanggenerálásnál a szokásos minta:

1. készítse elő a modellazonosítót, a promptot és a támogatott paramétereket
2. adjon hozzá idempotenciakulcsot a biztonságos újrapróbálkozásokhoz
3. küldje be a kérést a generálási végponton
4. mentse el a nyilvános feladatazonosítót
5. kérdezze le az állapotot, amíg a feladat végállapotba nem ér

A kérés formájához használja a Generálás létrehozása, az eredménykezeléshez pedig a Generálási állapot dokumentációt.

A terméknek a queued, processing, succeeded és failed állapotokat felhasználó számára látható állapotként kell kezelnie. Ne kényszerítse a felhasználókat rendszer-részletek olvasására vagy arra, hogy találgassák, miért lassú egy feladat.

5. lépés: Chatmodellekhez használja a Chat API-t

A chatmodelleknek a Chat API útvonalat kell használniuk, nem a generálási végpontot.

Ez azért fontos, mert a chatmunka másképp viselkedik:

• a chatfordulók API-val létrehozott munkamenetekhez tartozhatnak
• a nem streamelt és az SSE streamelt válaszok eltérő felhasználói élményt adnak
• a képmellékletek a Files API-ból származó fájlazonosítókat használnak
• a kreditek elszámolása a chatfordulót követi, nem egy szokásos aszinkron médiafeladatot

Ha a termékének saját felületén belüli asszisztensi válaszra van szüksége, a Chat API lehet a megfelelő út. Ha a felhasználó még ötleteket fedez fel, a Rivya Chat vagy a Studio jobb választás lehet.

6. lépés: Kezdje lekérdezéssel, majd adjon hozzá webhookokat

Első verzióban a lekérdezés könnyebben átlátható.

Adja hozzá az API webhookok használatát, amikor:

• a terméknek sok aszinkron feladata van
• a várakozó klienseknek nem kellene közvetlenül lekérdezniük
• az alsóbb rendszereknek aláírt befejezési eseményekre van szükségük
• az újrapróbálkozás és a duplikátumkezelés már meg van tervezve

A webhook-fogadóknak egyszerűnek és szigorúnak kell lenniük: ellenőrizzék az aláírást, fogadjanak duplikátumbiztos eseményeket, frissítsenek egyetlen termékrekordot, és csak azt naplózzák, amit biztonságos naplózni.

7. lépés: Tegye láthatóvá a krediteket a termékben

A Rivya API ugyanazokat a fiókkrediteket használja, mint a Studio.

Az integrációnak el kell döntenie, ebből mennyit mutat meg. Legalább a csapatnak tudnia kell:

• melyik fiókhoz tartozik az API-kulcs
• melyik munkafolyamat fogyaszthat krediteket
• mi történik, ha túl kevés a kredit
• hogyan magyarázzák el a sikertelen generálási állapotokat
• hová irányítsanak valakit kreditekkel és számlázással kapcsolatos kérdések esetén

A felhasználó felé látható pénztárcamodellhez használja az API kreditek, a Rivya kreditek és számlázás útmutató és a Hogyan gondolkodjon a Rivya kreditekről, csomagokról és előfizetésekről útmutatókat.

Egy kis első verzió

Egy jó első verzió szándékosan korlátozott.

Például:

1. egy API-kulcs
2. egy kiválasztott képmodell
3. még nincs fájlfeltöltés
4. egy generálási kérés
5. egy állapotlekérdezési útvonal
6. egy egyszerű eredmény-előnézet a termékben
7. egy világos kredithiba-üzenet

Ez a verzió bizonyítja a kapcsolatot, mielőtt további mozgó részeket adna hozzá.

Egy teljesebb verzió

Miután az első verzió működik, egy teljesebb munkafolyamat hozzáadhatja:

• Files API referenciaképekhez vagy videókhoz
• modellspecifikus paramétervezérlőket
• a termékrekordhoz kötött idempotenciát
• aláírt webhookokat a befejezéshez
• Chat API-t asszisztensi fordulókhoz
• szerveroldali eseménystreamet, ahol a chatnek élő kimenetre van szüksége
• adminisztrátori vagy support nézeteket a sikertelen feladatokhoz

Minden hozzáadásnak valós termékigényre kell válaszolnia. Ha csak nagyobbnak mutatja a demót, hagyja ki.

Gyakori integrációs hibák

Kerülje ezeket a mintákat:

• az összes API-funkció egyszerre történő bevezetését
• a kreditfelhasználás elrejtését a fióktulajdonos elől
• Studio-only feltételezések használatát API-folyamatban
• a fájlfeltöltések utólagos gondolatként kezelését
• generálási kérések idempotencia nélküli újrapróbálását
• Chat API használatát olyan feladatokhoz, amelyeknek aszinkron generálásnak kellene lenniük
• generálási végpontok használatát chatfordulókhoz
• teljes API-kulcsok, webhook-titkok vagy ideiglenes fájladatok naplózását

A legbiztonságosabb API-munkafolyamat egyértelmű a tulajdonlásban, az állapotban és a hibakezelésben.

Merre tovább

• Induljon a Developers oldalról a nyilvános API-központhoz.
• Használja a Rivya API gyorskezdés útmutatót az első kérés futtatásához.
• Modellazonosítók kiválasztása előtt használja az API modellek dokumentációt.
• A Files API használatát csak akkor vezesse be, ha a modellnek valóban referenciamédiára van szüksége.
• Chatfordulókhoz és streamelt chatválaszokhoz használja a Chat API útvonalat.
• Használja az API webhookok megoldást, amikor a lekérdezés már nem elég.
• Ha a munkafolyamatnak továbbra is emberi feltárásra van szüksége, automatizálás előtt olvassa el a Mikor használja a Rivya API-t Studio helyett cikket.