Integrasi Rivya API yang baik bukan hanya satu request ke satu model.

Sebagian besar workflow produk nyata punya rantai kecil: memilih model yang tepat, menyiapkan input, mengunggah file referensi saat perlu, mengirim job, memantau status, menangani kredit, dan memberi tahu produk ketika hasilnya siap.

Artikel ini menunjukkan bentuk perencanaannya. Gunakan Quickstart Rivya API untuk jalur runnable yang paling singkat, dan gunakan dokumen API untuk field request yang tepat.

Mulai Dari Momen Produk

Sebelum memilih endpoint, jelaskan momen produk dalam satu kalimat.

Contoh:

Buat draf gambar produk saat penjual mengirim brief listing.
Buat konsep video pendek setelah campaign manager menyetujui arah still.
Kirim giliran chat di dalam alat riset internal dan stream respons kembali ke pengguna.
Upload gambar referensi, kirim request model yang didukung, dan beri tahu pengguna saat hasilnya siap.

Kalimat itu mencegah integrasi berubah menjadi kumpulan panggilan API yang longgar.

Petakan Workflow Sebelum Menulis Kode

Gunakan tabel ini sebelum membuka schema request.

Langkah workflow	Pertanyaan produk	Area API
Akses akun	Akun Rivya mana yang memiliki penggunaan ini?	Autentikasi API
Pilihan model	ID model publik mana yang cocok untuk pekerjaan ini?	Model API
Input referensi	Apakah model membutuhkan media yang diunggah?	Files API
Generasi	Apakah ini job async gambar, video, atau audio?	Membuat Generasi
Chat	Apakah ini giliran model chat, bukan job generasi?	Chat API
Status	Bagaimana produk tahu hasilnya sudah siap?	Status Generasi
Event selesai	Apakah sistem lain harus menerima callback bertanda tangan?	API Webhooks
Kredit	Bagaimana tim memahami biaya?	Credits API

Workflow harus cukup jelas sehingga setiap area API punya alasan untuk ada.

Langkah 1: Buat Key Untuk Integrasi

Buat API key untuk app, environment, atau workflow spesifik yang akan menggunakannya.

Hindari memakai satu key untuk semua hal. Menamai key berdasarkan tujuan membuat review nanti lebih mudah:

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

Baca Autentikasi API sebelum menyimpan key. Secret lengkap hanya ditampilkan sekali, jadi tim Anda harus segera menyimpannya di secret store server-side yang tepat.

Langkah 2: Pilih Model Dari Daftar Public API

Jangan menanam sebuah model secara permanen hanya karena model itu berhasil dalam uji manual.

Gunakan Model API dan Referensi API Model untuk mengonfirmasi:

ID model publik
apakah tersedia melalui API
mode input yang didukung
ekspektasi prompt dan parameter
apakah Files API diperlukan
perilaku kredit dan catatan kesiapan

Di sinilah banyak integrasi menjadi lebih bersih. Model yang sempurna untuk uji manual di Studio belum tentu menjadi model pertama yang tepat untuk alur produk otomatis.

Langkah 3: Putuskan Apakah Files API Masuk Versi Pertama

Jika model bisa berjalan dari input teks, jaga versi pertama tetap hanya teks.

Tambahkan Files API hanya ketika workflow benar-benar membutuhkan media referensi.

Ketika memang perlu, definisikan:

jenis file apa yang diterima produk
siapa yang memiliki langkah cleanup file
apa yang terjadi ketika upload gagal
bagaimana data file yang dikembalikan diteruskan ke parameter model
apakah file yang sama harus digunakan ulang atau diunggah lagi

Ini mencegah pengalaman file yang rapuh tersembunyi di balik tombol generate yang terlihat bersih.

Langkah 4: Kirim Satu Job Generasi

Untuk generasi gambar, video, dan audio, pola normalnya adalah:

siapkan ID model, prompt, dan params yang didukung
tambahkan idempotency key untuk retry yang aman
kirim melalui endpoint generasi
simpan public task ID
polling status sampai task mencapai status terminal

Gunakan Membuat Generasi untuk bentuk request dan Status Generasi untuk penanganan hasil.

Produk harus memperlakukan queued, processing, succeeded, dan failed sebagai status yang terlihat oleh pengguna. Jangan membuat pengguna membaca detail sistem atau menebak mengapa job lambat.

Langkah 5: Gunakan Chat API Untuk Model Chat

Model chat harus menggunakan Chat API, bukan endpoint generasi.

Ini penting karena pekerjaan chat punya perilaku berbeda:

giliran chat dapat menjadi bagian dari session yang dibuat API
non-streaming dan SSE streaming punya pengalaman pengguna yang berbeda
attachment gambar memakai file ID dari Files API
penyelesaian kredit mengikuti giliran chat, bukan task media async biasa

Jika produk Anda membutuhkan jawaban assistant di dalam antarmukanya sendiri, Chat API mungkin jalur yang tepat. Jika pengguna masih menjelajahi ide, Rivya Chat atau Studio mungkin lebih baik.

Langkah 6: Mulai Dengan Polling, Lalu Tambahkan Webhooks

Untuk versi pertama, polling lebih mudah dinalar.

Tambahkan API Webhooks ketika:

produk punya banyak job async
client yang menunggu tidak seharusnya polling langsung
sistem downstream membutuhkan event selesai bertanda tangan
penanganan retry dan duplikat sudah dirancang

Penerima webhook sebaiknya membosankan dan ketat: verifikasi signature, terima event yang aman terhadap duplikat, perbarui satu record produk, dan log hanya hal yang aman dicatat.

Langkah 7: Buat Kredit Terlihat Di Produk

Rivya API menggunakan kredit akun yang sama dengan Studio.

Integrasi Anda harus memutuskan seberapa banyak informasi itu ditampilkan. Setidaknya, tim harus tahu:

akun mana yang memiliki API key
workflow mana yang dapat memakai kredit
apa yang terjadi ketika kredit terlalu rendah
bagaimana status generasi gagal dijelaskan
ke mana seseorang harus diarahkan untuk pertanyaan kredit dan billing

Gunakan Credits API, Credits & Billing di Rivya, dan Cara Memahami Kredit, Paket, dan Plan Rivya untuk model dompet yang terlihat oleh pengguna.

Versi Pertama yang Kecil

Versi pertama yang baik sengaja dibatasi.

Misalnya:

satu API key
satu model gambar yang dipilih
belum ada upload file
satu request generasi
satu jalur polling status
satu preview hasil sederhana di produk Anda
satu pesan error kredit yang jelas

Versi itu membuktikan koneksi sebelum menambahkan lebih banyak bagian bergerak.

Versi yang Lebih Lengkap

Setelah versi pertama bekerja, workflow yang lebih lengkap mungkin menambahkan:

Files API untuk gambar atau video referensi
kontrol parameter khusus model
idempotency yang terikat ke record produk Anda
webhook bertanda tangan untuk penyelesaian
Chat API untuk giliran assistant
event stream server-side ketika chat membutuhkan output live
tampilan admin atau support untuk job yang gagal

Setiap tambahan harus menjawab kebutuhan produk nyata. Jika hanya membuat demo terlihat lebih besar, tinggalkan dulu.

Kesalahan Integrasi Umum

Hindari pola ini:

memulai dengan semua fitur API sekaligus
menyembunyikan penggunaan kredit dari pemilik akun
memakai asumsi khusus Studio di alur API
memperlakukan upload file sebagai pikiran belakangan
melakukan retry request generasi tanpa idempotency
menggunakan Chat API untuk job yang seharusnya generasi async
menggunakan endpoint generasi untuk giliran chat
mencatat API key lengkap, secret webhook, atau detail file sementara

Workflow API yang paling aman eksplisit tentang kepemilikan, status, dan penanganan kegagalan.

Tujuan Berikutnya

Mulai dari Developers untuk hub Public API.
Gunakan Quickstart Rivya API untuk menjalankan request pertama.
Gunakan Model API sebelum memilih ID model.
Gunakan Files API hanya ketika model benar-benar membutuhkan media referensi.
Gunakan Chat API untuk giliran chat dan respons chat streaming.
Gunakan API Webhooks ketika polling tidak lagi cukup.
Jika workflow masih membutuhkan eksplorasi manusia, baca Kapan Menggunakan Rivya API Daripada Studio sebelum mengotomatiskannya.

Bangun Alur Kerja Multimodal dengan Rivya API