HappyOyster adalah model open-world interaktif real-time. Dari satu prompt bahasa alami dan gambar frame pertama, model ini menghasilkan dunia digital yang dapat Anda perankan, jelajahi, dan interaksi secara real-time, yang disajikan sebagai stream video live yang dapat diikuti. Sangat cocok untuk drama interaktif, pravisualisasi film, companion AI, dan World yang dapat dimainkan.
Untuk pameran model dan tips penulisan prompt, lihat Panduan HappyOyster.
HappyOyster menawarkan tiga mode pengalaman, masing-masing diterapkan secara independen untuk mencakup berbagai skenario:
HappyOyster menggunakan model integrasi server + klien:
Modul "Model Usage" di konsol belum mendukung statistik penggunaan world-model. Lihat penggunaan Anda melalui halaman penagihan sebagai gantinya.
Pengenalan
HappyOyster menawarkan tiga mode pengalaman, masing-masing diterapkan secara independen untuk mencakup berbagai skenario:
| Mode | Input | Interaksi |
|---|---|---|
| Adventure | Prompt + gambar frame pertama (landscape) | Perintah arah / kamera / aksi (sendCommand) |
| Directing | Prompt atau skrip terstruktur + gambar frame pertama (landscape), gambar referensi opsional (digunakan untuk pembuatan skrip dan referensi karakter) | Instruksi teks (sendInstruct) / daftar skrip; mendukung pause, rewind, resume |
| Acting | Prompt + gambar frame pertama (portrait 9:16 secara default, 16:9 juga didukung) | Instruksi teks (sendInstruct); mendukung pause dan resume; tidak mendukung rewind |
Arsitektur
HappyOyster menggunakan model integrasi server + klien:
- Server Anda mengelola siklus hidup World secara penuh melalui HappyOyster Open API (dengan API Key utama, melalui HTTPS REST standar): membuat / mengelola World, menukar kredensial, serta mengkueri riwayat dan artifact. Open API dibagi berdasarkan mode pengalaman menjadi tiga suite terpisah: Adventure, Directing, dan Acting.
- Klien Anda menghadirkan pengalaman real-time melalui HappyOyster SDK (dengan API Key sementara +
ticket, melalui channel audio / video real-time RTC), yang mendukung Android, iOS, dan Web. SDK mengenkapsulasi koneksi RTC, pemutaran video, polling status, dan perintah interaktif, sehingga Anda tidak perlu bekerja langsung dengan protokol real-time yang mendasarinya.
- Buat World dan peroleh kredensial di backend. Dengan API Key utama, backend Anda mengirim
POST /worldske HappyOyster Open API untuk membuat World, melakukan polling status pembuatan melaluiGET /worlds/build-status, lalu memperoleh kredensial pengalaman melaluiPOST /worlds/get-travel-credential. Backend mengirimkantokendanticketke klien. - Mulai pengalaman real-time di klien. Klien menggunakan SDK, API Key sementara, dan
ticket. PanggilinitializedanupdateToken, lalustartTravel(ticket). SDK kemudian masuk ke pengalaman melalui Open API, membuat koneksi RTC, serta mengembalikan View video dan callback status kepada klien. - Berinteraksi dari klien. Klien menggunakan SDK untuk memanggil
sendInstruct,sendCommand,pause, atauend. SDK memanggil API kontrol yang sesuai pada Open API. - Ambil artefak setelah sesi berakhir. Backend Anda mengirim
GET /travels/artifactske Open API untuk mengambil artefak.
Open API dan SDK
Tanggung Jawab
| Dimensi | HappyOyster Open API sisi server | HappyOyster SDK sisi klien |
|---|---|---|
| Pemanggil | Backend Anda | Aplikasi atau frontend web Anda |
| Kredensial | API Key utama (jangka panjang, hanya disimpan di server) | API Key sementara (token) + satu kali ticket (berumur pendek) |
| Tanggung jawab utama | Manajemen World (membuat, polling status, kueri, menghapus); pertukaran kredensial; kontrol Travel; kueri artifact | Koneksi RTC dan rendering video; perintah interaksi real-time; kontrol sesi; callback status |
| Komunikasi | HTTPS REST standar | Channel audio / video real-time RTC (dienkapsulasi di dalam SDK) |
| Platform yang didukung | Bahasa backend apa pun (Python, Java, Node.js, dll.) | Android, iOS, Web |
Peta Kapabilitas
| Kemampuan | Open API (server) | SDK (klien) |
|---|---|---|
| Membuat / mengelola World | Didukung | Tidak didukung |
| Polling status build World | Didukung | Tidak didukung |
Menukar ticket | Didukung | Tidak didukung (menggunakan ticket) |
| Memasukkan token autentikasi HTTP | Tidak didukung | Didukung (updateToken) |
| Masuk room + koneksi RTC | Didukung (dipanggil secara internal oleh SDK) | Didukung (Travel dimulai, dienkapsulasi di dalam SDK) |
| Pemutaran video real-time | Tidak didukung | Didukung (sematkan tampilan video yang disediakan SDK; untuk Acting, gunakan aspectRatio yang dikembalikan untuk mengatur orientasi portrait / landscape) |
| Polling status | Didukung (dipanggil secara internal oleh SDK) | Didukung (ditampilkan melalui callback status) |
| Instruksi teks Directing / Acting | Didukung (instruct) | Didukung (sendInstruct) |
| Perintah kontrol Adventure | Tidak didukung | Didukung (sendCommand; tidak tersedia di Acting) |
| Pause / resume | Didukung | Didukung (Directing dan Acting; panggilan Adventure ditolak oleh SDK dengan 103003) |
| Rewind | Didukung (rewind; khusus Directing) | Didukung (khusus Directing; mode lain ditolak dengan 103003) |
| Akhiri pengalaman | Didukung | Didukung (Travel berakhir, dienkapsulasi di dalam SDK) |
| Perbarui skrip (ScriptList) | Didukung (update-script; Directing scriptlist saja. Acting dan Directing simple mengembalikan 409000) | Tidak didukung |
| Kueri riwayat Travel | Didukung | Tidak didukung |
| Mengambil artifact video | Didukung | Tidak didukung |
SDK tidak bertanggung jawab atas pembuatan atau pengelolaan World. Mode Directing script (Script List) hanya tersedia di sisi server; SDK hanya menangani streaming, pemutaran, dan input instruksi teks.
Skenario
| Skenario | Mode yang Direkomendasikan | API server utama | Kemampuan SDK klien utama |
|---|---|---|---|
| Game interaktif / World yang dapat dimainkan | Adventure | Membuat World → pertukaran kredensial | sendCommand + callback status |
| Companion AI / pemandu virtual | Adventure | Membuat dengan gambar frame pertama + prompt | Pengalaman real-time + tampilan video |
| Drama pendek interaktif / pravisualisasi film | Directing | simple prompt atau scriptlist skrip terstruktur | sendInstruct + pause / rewind |
| Panggilan video / companion portrait | Acting | Wajib prompt + firstFrameImage, opsional aspectRatio | sendInstruct + pause / resume (tanpa rewind) |
| Platform konten / pembuatan turunan | Directing | artifacts diekspor setelah sesi berakhir | Pengalaman + pengambilan artifact sisi server |
| Simulasi edukasi | Adventure | Membangun adegan dengan gambar frame pertama + prompt | Pengalaman masuk room yang cepat |
Batasan
- Aturan rasio aspek:
- Adventure:
firstFrameImagewajib diisi; rasio aspek video mengikuti gambar bingkai pertama. - Directing:
firstFrameImagebersifat opsional dalam sub-modesimpledan wajib dalam sub-modescriptlist. Jika disediakan, gambar harus berorientasi landscape (lebar / tinggi 1.5–2.0) dan rasio aspek mengikuti gambar frame pertama; nilaiaspectRatioapa pun yang diteruskan saat pembuatan akan diabaikan. - Acting:
firstFrameImagewajib diisi; rasio aspek dikontrol olehaspectRatiosaat pembuatan, dengan default9:16(portrait), dan16:9dapat diteruskan secara eksplisit. Field ini dikembalikan saat masuk ke room dan dalam detail World, dan klien harus mengatur orientasi player sesuai dengan itu. Rasio aspek frame pertama harus sesuai dengan rasio aspek target, jika tidak400000akan dikembalikan.
- Adventure:
- Akses lintas model: World dan Travel terikat secara ketat pada model yang membuatnya; akses lintas model mengembalikan
403001(world) atau404000(travel). - Perbedaan mode: Acting tidak mendukung mundur (
rewind) atausendCommand; memanggil jeda / lanjutkan di Adventure mengembalikan103003.
Glosarium
- World: Definisi lengkap dari dunia digital, termasuk karakter, adegan, dan naskah. Sebuah World dapat dibangun sebelumnya dan digunakan kembali; ini adalah dasar dari setiap pengalaman.
- Travel: Sesi pengalaman real-time yang dimulai dari sebuah World. Sesi ini umumnya melewati tahap "initialize → prepare → running → (opsional pause / rewind) → end"; nilai status yang tepat bergantung pada masing-masing SDK — lihat referensi API SDK yang sesuai.
- ticket: Kredensial masuk ruang satu kali yang diterbitkan oleh server dan dikirimkan ke klien.
- token (API Key sementara): Kredensial lapisan HTTP untuk SDK klien, ditandatangani oleh server dan disuntikkan ke dalam SDK; harus diperbarui secara berkala.
Periksa Model Usage
Modul "Model Usage" di konsol belum mendukung statistik penggunaan world-model. Lihat penggunaan Anda melalui halaman penagihan sebagai gantinya.
Langkah Selanjutnya
- Mulai Cepat: Selesaikan integrasi ujung ke ujung.