Vytvořte multimodální workflow s Rivya API

Dobrá integrace Rivya API není jen jeden požadavek na jeden model.

Většina skutečných produktových workflow má malý řetězec: vybrat správný model, připravit vstup, podle potřeby nahrát referenční soubory, odeslat úlohu, sledovat stav, ošetřit kredity a upozornit produkt, až bude výsledek připravený.

Tento článek ukazuje plánovací tvar. Pro nejkratší spustitelnou cestu použijte Rychlý start Rivya API a přesná pole požadavků hledejte v API dokumentaci.

Začněte produktovým okamžikem

Než vyberete endpointy, popište produktový okamžik jednou větou.

Příklady:

• Vytvořit návrh produktového obrázku, když prodejce odešle brief nabídky.
• Vygenerovat krátký koncept videa poté, co campaign manager schválí statický směr.
• Poslat chatový tah v interním výzkumném nástroji a streamovat odpověď zpět uživateli.
• Nahrát referenční obrázek, odeslat podporovaný požadavek na model a upozornit uživatele, až bude výsledek připravený.

Tato věta zabrání tomu, aby se integrace změnila ve volnou sbírku API volání.

Zmapujte workflow před psaním kódu

Použijte tuto tabulku ještě před otevřením schématu požadavku.

Workflow by mělo být dost jasné na to, aby každá oblast API měla důvod existovat.

Krok 1: Vytvořte klíč pro integraci

Vytvořte API klíč pro konkrétní aplikaci, prostředí nebo workflow, které ho bude používat.

Nepoužívejte jeden klíč na všechno. Pojmenování klíčů podle účelu usnadňuje pozdější kontrolu:

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

Před uložením klíče si přečtěte Ověřování API. Celé tajemství se zobrazí pouze jednou, takže ho váš tým musí hned uložit do správného serverového úložiště tajných hodnot.

Krok 2: Vybírejte modely z veřejného API seznamu

Nezapisujte model natvrdo jen proto, že fungoval v ručním testu.

Pomocí Modely API a Reference modelového API ověřte:

• veřejné ID modelu
• zda je dostupný přes API
• podporovaný vstupní režim
• očekávání pro prompt a parametry
• zda je vyžadováno Files API
• chování kreditů a poznámky k připravenosti

Právě tady se mnoho integrací pročistí. Model, který je perfektní pro ruční test ve Studio, nemusí být nejlepší první model pro automatizovaný produktový tok.

Krok 3: Rozhodněte, zda je Files API součástí první verze

Pokud model umí běžet z textového vstupu, nechte první verzi text-only.

Files API přidejte jen tehdy, když workflow skutečně potřebuje referenční média.

Když je potřebuje, definujte:

• jaké typy souborů produkt přijímá
• kdo vlastní krok čištění souborů
• co se stane, když nahrání selže
• jak se vrácená data souboru předávají do parametrů modelu
• zda se má stejný soubor znovu použít, nebo nahrát znovu

Tím zabráníte tomu, aby se křehká práce se soubory schovala za čistě vypadající tlačítko generování.

Krok 4: Odešlete jednu generační úlohu

Pro generování obrázků, videa a audia je běžný vzor:

1. připravit ID modelu, prompt a podporované parametry
2. přidat idempotency key pro bezpečné opakování
3. odeslat přes generation endpoint
4. uložit veřejné ID úlohy
5. dotazovat stav, dokud úloha nedosáhne terminálního stavu

Pro tvar požadavku použijte Vytvoření generování a pro zpracování výsledku Stav generování.

Produkt by měl stavy queued, processing, succeeded a failed brát jako stavy viditelné pro uživatele. Nenuťte uživatele číst systémové detaily ani hádat, proč je úloha pomalá.

Krok 5: Pro chatové modely použijte Chat API

Chatové modely mají používat Chat API, ne generation endpoint.

Je to důležité, protože chatová práce má jiné chování:

• chatové tahy mohou patřit k sessions vytvořeným přes API
• non-streaming a SSE streaming mají odlišnou uživatelskou zkušenost
• obrazové přílohy používají file IDs z Files API
• vypořádání kreditů následuje chatový tah, ne běžnou asynchronní mediální úlohu

Pokud váš produkt potřebuje odpověď asistenta ve vlastním rozhraní, Chat API může být správná cesta. Pokud uživatel stále zkoumá nápady, Rivya Chat nebo Studio mohou být lepší.

Krok 6: Začněte pollingem a potom přidejte webhooky

Pro první verzi je polling snazší na pochopení.

API Webhooks přidejte, když:

• produkt má mnoho asynchronních úloh
• čekající klienti nemají pollovat přímo
• downstream systémy potřebují podepsané události dokončení
• retry a duplicate handling už jsou navržené

Příjemci webhooků by měli být nudní a přísní: ověřit podpis, přijmout události bezpečné při duplicitě, aktualizovat jeden produktový záznam a logovat jen to, co je bezpečné logovat.

Krok 7: Zviditelněte kredity v produktu

Rivya API používá stejné kredity účtu jako Studio.

Vaše integrace by měla rozhodnout, kolik z toho zobrazí. Minimálně by tým měl vědět:

• který účet vlastní API klíč
• které workflow může spotřebovávat kredity
• co se stane, když je kreditů příliš málo
• jak se vysvětlují neúspěšné stavy generování
• kam poslat člověka s otázkami ke kreditům a fakturaci

Pro uživatelsky viditelný model peněženky použijte Kredity API, Průvodce kredity a fakturací Rivya a Jak přemýšlet o kreditech, balíčcích a plánech Rivya.

Malá první verze

Dobrá první verze je záměrně omezená.

Například:

1. jeden API klíč
2. jeden vybraný obrazový model
3. zatím žádné nahrávání souborů
4. jeden generační požadavek
5. jedna cesta pro dotazování stavu
6. jeden jednoduchý náhled výsledku ve vašem produktu
7. jedna jasná chybová zpráva ke kreditům

Tato verze ověří spojení dřív, než přidáte další pohyblivé části.

Úplnější verze

Po zprovoznění první verze může úplnější workflow přidat:

• Files API pro referenční obrázky nebo videa
• ovládání parametrů specifických pro model
• idempotency navázanou na váš produktový záznam
• podepsané webhooky pro dokončení
• Chat API pro tahy asistenta
• server-side event stream tam, kde chat potřebuje živý výstup
• administrační nebo support pohledy pro neúspěšné úlohy

Každý doplněk má odpovídat skutečné produktové potřebě. Pokud jen zvětšuje demo, nechte ho stranou.

Časté chyby při integraci

Vyhněte se těmto vzorcům:

• začít se všemi API funkcemi najednou
• skrývat spotřebu kreditů před vlastníkem účtu
• používat předpoklady ze Studio-only prostředí v API toku
• brát nahrávání souborů jako dodatečný detail
• opakovat generační požadavky bez idempotency
• používat Chat API pro úlohy, které mají být asynchronním generováním
• používat generation endpoints pro chatové tahy
• logovat celé API klíče, webhook secrets nebo dočasné detaily souborů

Nejbezpečnější API workflow je explicitní v otázkách vlastnictví, stavu a práce se selháním.

Kam pokračovat

• Začněte na Developers, veřejném API hubu.
• Použijte Rychlý start Rivya API ke spuštění prvního požadavku.
• Před výběrem IDs modelů použijte Modely API.
• Files API použijte jen tehdy, když model skutečně potřebuje referenční média.
• Chat API použijte pro chatové tahy a streamované chatové odpovědi.
• API Webhooks použijte, když polling už nestačí.
• Pokud workflow stále potřebuje lidské prozkoumávání, přečtěte si Kdy použít Rivya API místo Studia, než ho automatizujete.