Integrasi Rivya API yang baik bukan sekadar satu request kepada satu model.

Kebanyakan aliran kerja produk sebenar mempunyai rantaian kecil: pilih model yang betul, sediakan input, muat naik fail rujukan apabila perlu, hantar tugas, pantau status, kendalikan kredit dan maklumkan produk apabila hasil sudah sedia.

Artikel ini menunjukkan bentuk perancangan. Gunakan Rivya API Quickstart untuk laluan boleh jalan yang paling ringkas, dan gunakan dokumen API untuk medan request yang tepat.

Mulakan dengan Detik Produk

Sebelum memilih endpoint, terangkan detik produk dalam satu ayat.

Contoh:

Cipta draf imej produk apabila penjual menghantar taklimat listing.
Jana konsep video pendek selepas pengurus kempen meluluskan arah imej pegun.
Hantar satu giliran chat dalam tool penyelidikan dalaman dan strim respons kembali kepada pengguna.
Muat naik imej rujukan, hantar permintaan model yang disokong, dan maklumkan pengguna apabila hasil sudah sedia.

Ayat itu menghalang integrasi daripada menjadi himpunan longgar API call.

Petakan Aliran Kerja Sebelum Menulis Kod

Gunakan jadual ini sebelum membuka skema request.

Langkah aliran kerja	Soalan produk	Kawasan API
Akses akaun	Akaun Rivya mana memiliki penggunaan?	API Authentication
Pilihan model	ID model awam mana sesuai dengan tugas ini?	API Models
Input rujukan	Adakah model memerlukan media yang dimuat naik?	Files API
Penjanaan	Adakah ini tugas imej, video atau audio async?	Create Generation
Chat	Adakah ini giliran model chat, bukan tugas penjanaan?	Chat API
Status	Bagaimana produk tahu hasil sudah sedia?	Generation Status
Event siap	Patutkah sistem lain menerima callback bertandatangan?	API Webhooks
Kredit	Bagaimana pasukan memahami kos?	API Credits

Aliran kerja harus cukup jelas supaya setiap kawasan API mempunyai sebab untuk wujud.

Langkah 1: Cipta Key untuk Integrasi

Cipta API key untuk app, environment atau aliran kerja khusus yang akan menggunakannya.

Elakkan menggunakan satu key untuk semuanya. Menamakan key mengikut tujuan menjadikan semakan kemudian lebih mudah:

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

Baca API Authentication sebelum menyimpan key. Secret penuh hanya dipaparkan sekali, jadi pasukan anda perlu menyimpannya dalam server-side secret store yang betul dengan segera.

Langkah 2: Pilih Model daripada Senarai API Awam

Jangan hard-code model hanya kerana ia berfungsi dalam ujian manual.

Gunakan API Models dan Model API Reference untuk mengesahkan:

ID model awam
sama ada ia tersedia melalui API
mod input yang disokong
jangkaan prompt dan parameter
sama ada Files API diperlukan
kelakuan kredit dan nota kesediaan

Di sinilah banyak integrasi menjadi lebih bersih. Model yang sempurna untuk ujian Studio manual mungkin bukan model pertama yang betul untuk aliran produk automatik.

Langkah 3: Tentukan Sama Ada Files API Sebahagian daripada Versi Pertama

Jika model boleh berjalan daripada input teks, kekalkan versi pertama sebagai teks sahaja.

Tambah Files API hanya apabila aliran kerja benar-benar memerlukan media rujukan.

Apabila ia diperlukan, tentukan:

jenis fail yang diterima produk
siapa memiliki langkah pembersihan fail
apa yang berlaku apabila muat naik gagal
bagaimana data fail yang dikembalikan dihantar ke parameter model
sama ada fail yang sama patut digunakan semula atau dimuat naik lagi

Ini menghalang pengalaman fail yang rapuh daripada tersembunyi di sebalik butang generate yang kelihatan bersih.

Langkah 4: Hantar Satu Tugas Penjanaan

Untuk penjanaan imej, video dan audio, corak biasa ialah:

sediakan ID model, prompt dan params yang disokong
tambah idempotency key untuk retry yang selamat
hantar melalui endpoint penjanaan
simpan public task ID
poll status sehingga tugas mencapai keadaan terminal

Gunakan Create Generation untuk bentuk request dan Generation Status untuk pengendalian hasil.

Produk patut melayan queued, processing, succeeded dan failed sebagai state yang kelihatan kepada pengguna. Jangan suruh pengguna membaca butiran sistem atau meneka sebab sesuatu tugas lambat.

Langkah 5: Gunakan Chat API untuk Model Chat

Model chat harus menggunakan Chat API, bukan endpoint penjanaan.

Itu penting kerana kerja chat mempunyai kelakuan berbeza:

giliran chat boleh tergolong dalam sesi yang dicipta API
non-streaming dan SSE streaming memberi pengalaman pengguna yang berbeza
lampiran imej menggunakan file ID daripada Files API
penyelesaian kredit mengikuti giliran chat, bukan tugas media async biasa

Jika produk anda memerlukan jawapan assistant dalam interface sendiri, Chat API mungkin laluan yang betul. Jika pengguna masih meneroka idea, Rivya Chat atau Studio mungkin lebih baik.

Langkah 6: Mulakan dengan Polling, Kemudian Tambah Webhook

Untuk versi pertama, polling lebih mudah untuk difikirkan.

Tambah API Webhooks apabila:

produk mempunyai banyak tugas async
client yang menunggu tidak patut poll terus
sistem downstream memerlukan event siap bertandatangan
retry dan pengendalian duplicate sudah direka

Webhook receiver patut membosankan dan ketat: sahkan signature, terima event yang duplicate-safe, kemas kini satu rekod produk dan log hanya perkara yang selamat untuk dilog.

Langkah 7: Jadikan Kredit Kelihatan dalam Produk

Rivya API menggunakan kredit akaun yang sama seperti Studio.

Integrasi anda perlu memutuskan berapa banyak perkara itu ditunjukkan. Sekurang-kurangnya, pasukan perlu tahu:

akaun mana memiliki API key
aliran kerja mana boleh menggunakan kredit
apa yang berlaku apabila kredit terlalu rendah
bagaimana state penjanaan gagal diterangkan
ke mana seseorang perlu dihantar untuk soalan kredit dan billing

Gunakan API Credits, Credits & Billing dalam Rivya dan How to Think About Rivya Credits, Packs, and Plans untuk model wallet yang kelihatan kepada pengguna.

Versi Pertama yang Kecil

Versi pertama yang baik sengaja terhad.

Contohnya:

satu API key
satu model imej terpilih
belum ada muat naik fail
satu request penjanaan
satu laluan status polling
satu preview hasil ringkas dalam produk anda
satu mesej ralat kredit yang jelas

Versi itu membuktikan sambungan sebelum menambah lebih banyak bahagian bergerak.

Versi yang Lebih Lengkap

Selepas versi pertama berfungsi, aliran kerja lebih lengkap mungkin menambah:

Files API untuk imej atau video rujukan
kawalan parameter khusus model
idempotency yang terikat kepada rekod produk anda
webhook bertandatangan untuk completion
Chat API untuk giliran assistant
server-side event stream apabila chat memerlukan output live
paparan admin atau support untuk tugas gagal

Setiap tambahan harus menjawab keperluan produk sebenar. Jika ia hanya membuat demo kelihatan lebih besar, tinggalkan.

Kesilapan Integrasi Biasa

Elakkan corak ini:

bermula dengan setiap ciri API sekali gus
menyembunyikan penggunaan kredit daripada pemilik akaun
menggunakan andaian Studio-only dalam aliran API
melayan muat naik fail sebagai perkara kemudian
retry request penjanaan tanpa idempotency
menggunakan Chat API untuk tugas yang sepatutnya async generation
menggunakan endpoint penjanaan untuk giliran chat
melog API key penuh, webhook secret atau butiran fail sementara

Aliran kerja API yang paling selamat jelas tentang pemilikan, state dan pengendalian kegagalan.

Ke Mana Seterusnya

Mula daripada Developers untuk hub API awam.
Gunakan Rivya API Quickstart untuk menjalankan request pertama.
Gunakan API Models sebelum memilih model ID.
Gunakan Files API hanya apabila model benar-benar memerlukan media rujukan.
Gunakan Chat API untuk giliran chat dan respons chat streaming.
Gunakan API Webhooks apabila polling tidak lagi mencukupi.
Jika aliran kerja masih memerlukan eksplorasi manusia, baca When to Use Rivya API Instead of Studio sebelum mengautomasikannya.

Bina Aliran Kerja Multimodal dengan Rivya API