Hyvä Rivya API -integraatio ei ole vain yksi pyyntö yhdelle mallille.

Useimmissa todellisissa tuotetyönkuluissa on pieni ketju: valitse oikea malli, valmistele syöte, lataa viitetiedostot tarvittaessa, lähetä työ, seuraa tilaa, käsittele creditit ja ilmoita tuotteelle, kun tulos on valmis.

Tämä artikkeli näyttää suunnittelun muodon. Käytä Rivya API Quickstartia lyhimpään ajettavaan polkuun ja API-dokumentteja tarkkoihin pyyntökenttiin.

Aloita tuotehetkestä

Ennen endpointien valintaa kuvaa tuotehetki yhdellä lauseella.

Esimerkkejä:

Luo tuotekuvan luonnos, kun myyjä lähettää listausbriefin.
Generoi lyhyt videokonsepti sen jälkeen, kun kampanjapäällikkö hyväksyy still-suunnan.
Lähetä chat-vuoro sisäisessä tutkimustyökalussa ja striimaa vastaus takaisin käyttäjälle.
Lataa viitekuva, lähetä tuetun mallin pyyntö ja ilmoita käyttäjälle, kun tulos on valmis.

Tämä lause estää integraatiota muuttumasta irralliseksi API-kutsujen kokoelmaksi.

Kartoita työnkulku ennen koodin kirjoittamista

Käytä tätä taulukkoa ennen pyyntöskeeman avaamista.

Työnkulun vaihe	Tuotekysymys	API-alue
Tilin käyttöoikeus	Mikä Rivya-tili omistaa käytön?	API Authentication
Mallivalinta	Mikä julkinen malli-ID sopii tähän työhön?	API Models
Viitesyöte	Tarvitseeko malli ladattua mediaa?	Files API
Generointi	Onko tämä async-kuva-, video- vai audiotyö?	Create Generation
Chat	Onko tämä chat-mallin vuoro generointityön sijaan?	Chat API
Tila	Miten tuote tietää, että tulos on valmis?	Generation Status
Valmistumistapahtuma	Pitäisikö toisen järjestelmän saada allekirjoitettu callback?	API Webhooks
Creditit	Miten tiimi ymmärtää kustannuksen?	API Credits

Työnkulun pitäisi olla niin selkeä, että jokaisella API-alueella on syy olla olemassa.

Vaihe 1: Luo avain integraatiolle

Luo API-avain sille tietylle sovellukselle, ympäristölle tai työnkululle, joka käyttää sitä.

Vältä yhden avaimen käyttämistä kaikkeen. Avainten nimeäminen tarkoituksen mukaan helpottaa myöhempää arviointia:

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

Lue API Authentication ennen avaimen tallentamista. Koko salaisuus näytetään kerran, joten tiimin pitäisi tallentaa se heti oikeaan palvelinpuolen secret storeen.

Vaihe 2: Valitse mallit julkisesta API-listasta

Älä hard-koodaa mallia vain siksi, että se toimi manuaalisessa testissä.

Käytä API Models- ja Model API Reference -sivuja varmistaaksesi:

julkinen malli-ID
onko se saatavilla API:n kautta
tuettu syöttötila
promptin ja parametrien odotukset
tarvitaanko Files API:a
credit-käyttäytyminen ja valmiusmuistiinpanot

Tässä moni integraatio siistiytyy. Malli, joka on täydellinen manuaaliseen Studio-testiin, ei välttämättä ole oikea ensimmäinen malli automatisoituun tuotevirtaan.

Vaihe 3: Päätä, kuuluuko Files API ensimmäiseen versioon

Jos malli voi ajaa tekstisyötteestä, pidä ensimmäinen versio text-only-muotoisena.

Lisää Files API vain, kun työnkulku todella tarvitsee viitemediaa.

Kun se tarvitsee, määritä:

mitä tiedostotyyppejä tuote hyväksyy
kuka omistaa tiedostojen siivousvaiheen
mitä tapahtuu, kun lataus epäonnistuu
miten palautettu tiedostodata viedään malliparametreihin
käytetäänkö samaa tiedostoa uudelleen vai ladataanko se uudelleen

Tämä estää haurasta tiedostokokemusta piiloutumasta siistiltä näyttävän generate-painikkeen taakse.

Vaihe 4: Lähetä yksi generointityö

Kuva-, video- ja audiogeneroinnissa tavallinen malli on:

valmistele malli-ID, prompti ja tuetut parametrit
lisää idempotency-avain turvallisia uudelleenyrityksiä varten
lähetä generointipäätepisteen kautta
tallenna julkinen task ID
pollaa tilaa, kunnes työ saavuttaa terminaalitilan

Käytä Create Generation -sivua pyynnön muotoon ja Generation Status -sivua tulosten käsittelyyn.

Tuotteen pitäisi käsitellä queued, processing, succeeded ja failed käyttäjälle näkyvinä tiloina. Älä pakota käyttäjiä lukemaan järjestelmäyksityiskohtia tai arvaamaan, miksi työ on hidas.

Vaihe 5: Käytä Chat API:a chat-malleille

Chat-mallien pitäisi käyttää Chat API -rajapintaa, ei generointipäätepistettä.

Se merkitsee, koska chat-työllä on eri käyttäytyminen:

chat-vuorot voivat kuulua API:n luomiin sessioihin
ei-striimaavalla ja SSE-striimauksella on erilaiset käyttäjäkokemukset
kuvaliitteet käyttävät Files API:n file ID -tunnisteita
credit-selvitys seuraa chat-vuoroa tavallisen async-mediatyön sijaan

Jos tuotteesi tarvitsee avustajavastauksen omassa käyttöliittymässään, Chat API voi olla oikea polku. Jos käyttäjä vielä tutkii ideoita, Rivya Chat tai Studio voi olla parempi.

Vaihe 6: Aloita pollingilla ja lisää sitten webhookit

Ensimmäisessä versiossa polling on helpompi hahmottaa.

Lisää API Webhooks, kun:

tuotteella on paljon async-töitä
odottavien clienttien ei pitäisi pollata suoraan
downstream-järjestelmät tarvitsevat allekirjoitettuja valmistumistapahtumia
retry- ja duplicate-käsittely on jo suunniteltu

Webhook-vastaanottimien pitäisi olla tylsiä ja tiukkoja: varmista allekirjoitus, hyväksy duplikaattiturvalliset tapahtumat, päivitä yksi tuotetietue ja lokita vain se, mitä on turvallista lokittaa.

Vaihe 7: Tee creditit näkyviksi tuotteessa

Rivya API käyttää samoja tilin creditejä kuin Studio.

Integraation pitäisi päättää, kuinka paljon siitä näytetään. Vähintään tiimin pitäisi tietää:

mikä tili omistaa API-avaimen
mikä työnkulku voi kuluttaa creditejä
mitä tapahtuu, kun creditit ovat liian vähissä
miten epäonnistuneet generointitilat selitetään
minne käyttäjä ohjataan credit- ja laskutuskysymyksissä

Käytä API Credits-, Creditit ja laskutus Rivyassa- ja Kuinka ajatella Rivyan creditejä, paketteja ja suunnitelmia -sivuja käyttäjälle näkyvään lompakkomalliin.

Pieni ensimmäinen versio

Hyvä ensimmäinen versio on tarkoituksella rajattu.

Esimerkiksi:

yksi API-avain
yksi valittu kuvamalli
ei tiedostonlatausta vielä
yksi generointipyyntö
yksi tilan polling-polku
yksi yksinkertainen tulosesikatselu tuotteessasi
yksi selkeä credit-virheviesti

Tämä versio todistaa yhteyden ennen lisäliikkuvien osien lisäämistä.

Täydellisempi versio

Kun ensimmäinen versio toimii, täydempi työnkulku voi lisätä:

Files API:n viitekuville tai videoille
mallikohtaiset parametrikontrollit
tuotteesi tietueeseen sidotun idempotencyn
allekirjoitetut webhookit valmistumiseen
Chat API:n avustajavuoroihin
palvelinpuolen event streamin, kun chat tarvitsee live-tuotosta
admin- tai tukinäkymät epäonnistuneille töille

Jokaisen lisäyksen pitäisi vastata todelliseen tuotetarpeeseen. Jos se vain saa demon näyttämään suuremmalta, jätä se pois.

Yleiset integraatiovirheet

Vältä näitä malleja:

aloittamista kaikilla API-ominaisuuksilla kerralla
credit-käytön piilottamista tilin omistajalta
Studio-oletusten käyttämistä API-virrassa
tiedostolatausten käsittelemistä jälkiajatuksena
generointipyyntöjen uudelleenyrityksiä ilman idempotencyä
Chat API:n käyttämistä töihin, joiden pitäisi olla async-generointia
generointipäätepisteiden käyttämistä chat-vuoroihin
täysien API-avainten, webhook-salaisuuksien tai väliaikaisten tiedostoyksityiskohtien lokittamista

Turvallisin API-työnkulku on eksplisiittinen omistajuudesta, tilasta ja virheenkäsittelystä.

Minne mennä seuraavaksi

Aloita Developers-sivulta julkiseen API-keskukseen.
Käytä Rivya API Quickstartia ensimmäisen pyynnön ajamiseen.
Käytä API Models -sivua ennen malli-ID:iden valitsemista.
Käytä Files API -rajapintaa vain, kun malli todella tarvitsee viitemediaa.
Käytä Chat API -rajapintaa chat-vuoroihin ja striimattuihin chat-vastauksiin.
Käytä API Webhooks -rajapintaa, kun polling ei enää riitä.
Jos työnkulku tarvitsee yhä ihmisen tutkimista, lue Milloin käyttää Rivya API:a Studion sijaan ennen automatisointia.

Rakenna multimodaalinen työnkulku Rivya API:lla