Vytvořte multimodální pracovní postup s Rivya API

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

Většina skutečných produktových pracovních postupů tvoří krátký řetězec: vybrat správný model, připravit vstup, podle potřeby nahrát referenční soubory, odeslat úlohu, sledovat stav, spravovat 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.

Následující proces popisuje implementovaný kontrakt veřejného API. Před vývojem ověřte, že je přístup k veřejnému API zapnutý pro nasazení i účet, vybraný model podporuje API a volitelné funkce, například webhooky, jsou skutečně dostupné.

Začněte produktovým okamžikem

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

Příklady:

• Vytvořit návrh produktového obrázku, když prodejce odešle zadání 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 pracovní postup před psaním kódu

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

Pracovní postup by měl být natolik jasný, aby každá oblast API měla svůj opodstatněný účel.

Krok 1: Vytvořte klíč pro integraci

Vytvořte API klíč pro konkrétní aplikaci, prostředí nebo pracovní postup, 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

• podepsané webhooky o dokončení, pokud je tato funkce zapnutá

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í Modelů API a dokumentace modelů 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í vyjasní. Model, který je ideální pro ruční test ve Studiu, nemusí být nejlepší první volbou pro automatizovaný produktový tok.

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

Pokud model umí pracovat pouze s textovým vstupem, ponechte první verzi čistě textovou.

Files API přidejte jen tehdy, když pracovní postup 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 koncový bod generování

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 koncový bod generování.

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 pravidelným dotazováním a potom přidejte webhooky

Pro první verzi je pravidelné dotazování na stav snazší na pochopení.

Pokud jsou webhooky pro dané nasazení zapnuté, přidejte Webhooky API, 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 zůstat jednoduchí a přísní: ověřit podpis, bezpečně přijmout i duplicitní události, aktualizovat jeden produktový záznam a zaznamenat jen bezpečné údaje.

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é pracovní postupy mohou 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ší pracovní postup 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 koncové body generování pro chatové tahy

• zapisovat do protokolů celé API klíče, tajné hodnoty webhooků nebo dočasné údaje o souborech

Nejbezpečnější pracovní postup s API má jasně vymezené vlastnictví, stavy i zpracování selhání.

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.

• Webhooky API použijte, když už pravidelné dotazování nestačí a přístup k webhookům je zapnutý.

• Pokud pracovní postup stále vyžaduje lidské posouzení, přečtěte si Kdy použít Rivya API místo Studia, než ho automatizujete.