Rakenna multimodaalinen työnkulku Rivya API:lla

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 krediitit ja ilmoita tuotteelle, kun tulos on valmis.

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

Alla oleva työnkulku kuvaa toteutettua julkisen API:n sopimusta. Varmista ennen rakentamista, että julkinen API on käytössä kyseisessä ympäristössä ja tilillä, valittu malli on API-valmis ja valinnaiset ominaisuudet, kuten webhookit, ovat todella saatavilla.

Aloita tuotehetkestä

Ennen päätepisteiden valintaa kuvaa tuotehetki yhdellä lauseella.

Esimerkkejä:

• Luo tuotekuvan luonnos, kun myyjä lähettää listausbriiffin.

• 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 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-todennus ennen avaimen tallentamista. Koko salaisuus näytetään kerran, joten tiimin pitäisi tallentaa se heti oikeaan palvelinpuolen salaisuuksien säilytyspaikkaan.

Vaihe 2: Valitse mallit julkisesta API-listasta

Älä kovakoodaa mallia vain siksi, että se toimi manuaalisessa testissä.

Käytä API-mallit- ja mallien API-viite -sivuja varmistaaksesi:

• julkinen malli-ID

• onko se saatavilla API:n kautta

• tuettu syöttötila

• kehotteen ja parametrien odotukset

• tarvitaanko Files API:a

• krediittikä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 pelkkänä tekstinä.

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 generointipainikkeen taakse.

Vaihe 4: Lähetä yksi generointityö

Kuva-, video- ja audiogeneroinnissa tavallinen malli on:

1. valmistele malli-ID, kehote ja tuetut parametrit

2. lisää idempotenssiavain turvallisia uudelleenyrityksiä varten

3. lähetä generointipäätepisteen kautta

4. tallenna julkinen tehtävä-ID

5. kysy tilaa, kunnes työ saavuttaa päätetilan

Käytä generoinnin luonti -sivua pyynnön muotoon ja generoinnin tila -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 tiedosto-ID-tunnisteita

• krediittiselvitys seuraa chat-vuoroa tavallisen asynkronisen 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 tilakyselyllä ja lisää sitten webhookit

Ensimmäisessä versiossa tilakysely on helpompi hahmottaa.

Jos webhookit on otettu käyttöön kyseisessä ympäristössä, lisää API-webhookit, kun:

• tuotteella on paljon asynkronisia töitä

• odottavien asiakkaiden ei pitäisi kysyä tilaa suoraan

• jatkojärjestelmät tarvitsevat allekirjoitettuja valmistumistapahtumia

• uudelleenyritys- ja duplikaattikä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 krediitit näkyviksi tuotteessa

Rivya API käyttää samoja tilin krediittejä 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 krediittejä

• mitä tapahtuu, kun krediitit ovat liian vähissä

• miten epäonnistuneet generointitilat selitetään

• minne käyttäjä ohjataan krediitti- ja laskutuskysymyksissä

Käytä API-krediitit-, Krediitit ja laskutus Rivyassa- ja Miten ajatella Rivyan krediittejä, krediittipaketteja ja tilauspaketteja -sivuja käyttäjälle näkyvään lompakkomalliin.

Pieni ensimmäinen versio

Hyvä ensimmäinen versio on tarkoituksella rajattu.

Esimerkiksi:

1. yksi API-avain

2. yksi valittu kuvamalli

3. ei tiedostonlatausta vielä

4. yksi generointipyyntö

5. yksi tilakyselypolku

6. yksi yksinkertainen tulosesikatselu tuotteessasi

7. yksi selkeä krediittivirheviesti

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 idempotenssin

• allekirjoitetut webhookit valmistumiseen, kun ominaisuus on käytössä

• Chat API:n avustajavuoroihin

• palvelinpuolen tapahtumavirran, kun chat tarvitsee reaaliaikaista 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

• krediittikäytön piilottamista tilin omistajalta

• Studio-oletusten käyttämistä API-virrassa

• tiedostolatausten käsittelemistä jälkiajatuksena

• generointipyyntöjen uudelleenyrityksiä ilman idempotenssia

• Chat API:n käyttämistä töihin, joiden pitäisi olla asynkronista 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 -pika-aloitusta ensimmäisen pyynnön ajamiseen.

• Käytä API-mallit -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-webhookit -rajapintaa, kun tilakysely ei enää riitä ja webhook-käyttöoikeus on käytössä.

• Jos työnkulku tarvitsee yhä ihmisen tutkimista, lue Milloin käyttää Rivya API:a Studion sijaan ennen automatisointia.