Bangun Alur Kerja Multimodal dengan Rivya API

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

Sebagian besar alur kerja produk nyata punya rantai kecil: memilih model yang tepat, menyiapkan masukan, mengunggah berkas referensi saat perlu, mengirim pekerjaan, memantau status, menangani kredit, dan memberi tahu produk ketika hasilnya siap.

Artikel ini menunjukkan cara merencanakannya. Gunakan Panduan memulai Rivya API untuk jalur siap pakai yang paling singkat, lalu lihat dokumentasi API untuk rincian kolom permintaan.

Alur berikut menjelaskan kontrak Public API yang telah diterapkan. Sebelum membangun, pastikan akses Public API aktif untuk penerapan dan akun, model terpilih siap digunakan melalui API, serta fitur opsional seperti webhook benar-benar tersedia.

Mulai Dari Momen Produk

Sebelum memilih titik akhir, jelaskan momen produk dalam satu kalimat.

Contoh:

• Buat draf gambar produk saat penjual mengirim ringkasan untuk daftar produk.

• Buat konsep video pendek setelah pengelola kampanye menyetujui arah gambar diam.

• Kirim giliran chat di alat riset internal dan alirkan respons kembali kepada pengguna.

• Unggah gambar referensi, kirim permintaan ke model yang didukung, lalu beri tahu pengguna saat hasilnya siap.

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

Petakan Alur Kerja Sebelum Menulis Kode

Gunakan tabel ini sebelum membuka skema permintaan.

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

Langkah 1: Buat Kunci untuk Integrasi

Buat kunci API khusus untuk aplikasi, lingkungan, atau alur kerja yang akan menggunakannya.

Hindari memakai satu kunci untuk semua hal. Menamai kunci berdasarkan tujuan membuat tinjauan nanti lebih mudah:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

Baca Autentikasi API sebelum menyimpan kunci. Nilai rahasia lengkap hanya ditampilkan sekali, jadi tim harus segera menyimpannya di tempat penyimpanan rahasia pada sisi server.

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 masukan 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 masukan teks, jaga versi pertama tetap hanya teks.

Tambahkan Files API hanya ketika alur kerja benar-benar membutuhkan media referensi.

Ketika memang perlu, definisikan:

• jenis berkas apa yang diterima produk

• siapa yang memiliki langkah pembersihan berkas

• apa yang terjadi ketika unggahan gagal

• bagaimana data berkas yang dikembalikan diteruskan ke parameter model

• apakah berkas yang sama harus digunakan ulang atau diunggah lagi

Ini mencegah pengalaman berkas yang rapuh tersembunyi di balik tombol menghasilkan yang terlihat bersih.

Langkah 4: Kirim Satu Pekerjaan Generasi

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

1. siapkan ID model, prompt, dan parameter yang didukung

2. tambahkan kunci idempotensi agar percobaan ulang tetap aman

3. kirim melalui titik akhir generasi

4. simpan ID tugas publik

5. periksa status secara berkala sampai tugas mencapai keadaan akhir

Gunakan Membuat Generasi untuk bentuk permintaan 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 pekerjaan lambat.

Langkah 5: Gunakan Chat API Untuk Model Chat

Model chat harus menggunakan Chat API, bukan titik akhir generasi.

Ini penting karena pekerjaan chat punya perilaku berbeda:

• giliran chat dapat menjadi bagian dari sesi yang dibuat API

• respons penuh dan aliran SSE memberi pengalaman pengguna yang berbeda

• lampiran gambar memakai berkas ID dari Files API

• penyelesaian kredit mengikuti giliran chat, bukan tugas media asinkron biasa

Jika produk Anda membutuhkan jawaban asisten 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, pemeriksaan berkala lebih mudah dinalar.

Jika webhook aktif untuk penerapan, tambahkan API Webhooks ketika:

• produk punya banyak pekerjaan asinkron

• klien yang menunggu tidak seharusnya memeriksa status secara langsung dan berulang

• sistem lanjutan membutuhkan peristiwa selesai bertanda tangan

• penanganan percobaan ulang dan duplikat sudah dirancang

Penerima webhook sebaiknya sederhana dan ketat: verifikasi tanda tangan, terima peristiwa secara idempoten, perbarui satu catatan produk, dan catat hanya informasi yang aman.

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 kunci

• alur kerja 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 penagihan

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

Versi Pertama yang Kecil

Versi pertama yang baik sengaja dibatasi.

Misalnya:

1. satu API kunci

2. satu model gambar yang dipilih

3. belum ada unggahan berkas

4. satu permintaan generasi

5. satu jalur pemeriksaan berkala status

6. satu pratinjau hasil sederhana di produk Anda

7. satu pesan kesalahan kredit yang jelas

Versi itu membuktikan koneksi sebelum menambahkan lebih banyak bagian bergerak.

Versi yang Lebih Lengkap

Setelah versi pertama bekerja, alur kerja yang lebih lengkap mungkin menambahkan:

• Files API untuk gambar atau video referensi

• kontrol parameter khusus model

• idempotensi yang terikat ke catatan produk Anda

• webhook bertanda tangan untuk penyelesaian saat fitur tersebut aktif

• Chat API untuk giliran asisten

• peristiwa aliran sisi server ketika chat membutuhkan hasil aktif

• tampilan administrator atau dukungan untuk pekerjaan 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 unggahan berkas sebagai pikiran belakangan

• melakukan percobaan ulang permintaan generasi tanpa idempotensi

• menggunakan Chat API untuk pekerjaan yang seharusnya generasi asinkron

• menggunakan titik akhir generasi untuk giliran chat

• mencatat API kunci lengkap, rahasia webhook, atau detail berkas sementara

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

Tujuan Berikutnya

• Mulai dari Pengembang untuk pusat Public API.

• Gunakan Mulai cepat Rivya API untuk menjalankan permintaan 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 aliran langsung.

• Gunakan API Webhooks ketika pemeriksaan berkala tidak lagi cukup dan akses webhook telah diaktifkan.

• Jika alur kerja masih membutuhkan eksplorasi manusia, baca Kapan Menggunakan Rivya API Daripada Studio sebelum mengotomatiskannya.