# API Qwen Character Referensi API lengkap untuk model roleplay karakter Qwen dari Alibaba. Model Qwen Character menggunakan endpoint chat completions Flaq AI, tetapi juga mendukung bidang khusus karakter untuk memori jangka panjang, simulasi chat grup, dan kelanjutan assistant parsial. ## Varian Model API ini mendukung dua varian model: | Model | ID | Deskripsi | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | Roleplay karakter dengan kualitas lebih tinggi | | **Qwen Flash Character** | `qwen-flash-character` | Roleplay karakter yang lebih cepat dan lebih terjangkau | ## Perbandingan Cepat | Fitur | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | Input teks | Wajib ✅ | Wajib ✅ | | Input gambar | Tidak didukung ❌ | Tidak didukung ❌ | | Memori jangka panjang | Opsional | Opsional | | `temperature` | Opsional | Opsional | | `seed` | Opsional | Opsional | | Respons streaming | SSE | SSE | ## Cara Kerja Roleplay Karakter Gunakan pesan `system`, `user`, dan `assistant` normal untuk roleplay satu karakter. Letakkan instruksi persona yang stabil di pesan `system` untuk permintaan saat ini. Saat memori jangka panjang diaktifkan, letakkan profil karakter yang dapat digunakan ulang di `profile`. Untuk simulasi chat grup, Qwen Character tidak otomatis menyimpulkan nama pembicara dari `profile`. Pemanggil harus menulis nama pembicara di awal setiap `content` pesan, seperti `Cheng Yi:` atau `Ling Lu:`. Agar model melanjutkan sebagai karakter tertentu, tambahkan pesan assistant terakhir dengan `content` berupa prefiks pembicara target dan tetapkan `partial: true`. `partial` adalah bidang tingkat pesan pada pesan assistant terakhir. Ini bukan parameter permintaan tingkat atas. ## Qwen Plus Character ### Titik Akhir ```http POST /api/v1/chat/completions ``` ### Parameter Permintaan #### Wajib | Parameter | Tipe | Deskripsi | |-----------|------|-------------| | `model` | string | Harus berupa `"qwen-plus-character"` | | `messages` | array | Pesan berurutan dengan role `system`, `user`, dan `assistant` opsional. | | `stream` | boolean | `true` untuk SSE, `false` untuk satu respons JSON. | #### Header | Header | Wajib | Deskripsi | |--------|----------|-------------| | `Authorization` | Wajib | Kunci API, dengan format `Bearer YOUR_API_KEY`. | | `Content-Type` | Wajib | Gunakan `application/json`. | | `Accept` | Wajib | Gunakan `text/event-stream` saat `stream` bernilai `true`; gunakan `application/json` saat `stream` bernilai `false`. | | `x-session` | Wajib saat memori jangka panjang diaktifkan | ID sesi yang ditentukan pengguna untuk isolasi dan recall memori jangka panjang. Memori diisolasi berdasarkan kunci pengguna, sehingga pengguna berbeda dapat memakai ulang ID sesi yang sama tanpa berbagi memori. | #### Dukungan Pesan | Bidang | Teks | File | Gambar | |-------|------|------|-------| | `messages` | Wajib ✅ | Tidak didukung ❌ | Tidak didukung ❌ | #### Bidang Pesan | Bidang | Tipe | Wajib | Deskripsi | |-------|------|----------|-------------| | `role` | string | Wajib | Mendukung `system`, `user`, dan `assistant`. | | `content` | string | Wajib | Teks pesan. Untuk simulasi chat grup, sertakan nama pembicara secara manual di awal, seperti `Ling Lu:`. | | `partial` | boolean | Opsional | Hanya digunakan pada pesan assistant terakhir. Tetapkan ke `true` saat `content` adalah prefiks yang harus dilanjutkan oleh model. | #### Opsional | Parameter | Tipe | Rentang | Deskripsi | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | Token output maksimum. | | `temperature` | number | `0.0` - `1.0` | Mengontrol keacakan respons. | | `seed` | integer | `0` - `2147483647` | Seed acak untuk output yang dapat direproduksi. Ini tidak terkait dengan jendela konteks percakapan. | | `profile` | string | — | Profil karakter. Wajib saat `enable_long_term_memory` bernilai `true`. `profile` tidak otomatis menambahkan nama pembicara ke pesan. | | `enable_long_term_memory` | boolean | — | Mengaktifkan memori jangka panjang untuk permintaan. Memerlukan `profile` dan header `x-session`. | | `memory_entries` | integer | — | Jumlah entri memori yang akan di-recall atau dipertahankan untuk sesi. Tidak ada batas rentang tetap yang saat ini ditampilkan oleh dokumentasi resmi. | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | Jenis memori yang dilewati saat menyimpan untuk permintaan ini. | Saat memori jangka panjang diaktifkan, Anda harus menyediakan: - header permintaan `x-session` - `profile` di body permintaan - `enable_long_term_memory: true` `skip_save_types` mendukung nilai berikut: | Nilai | Arti | |-------|---------| | `system` | Lewati penyimpanan pesan `system` yang ditambahkan dalam permintaan ini. | | `user` | Lewati penyimpanan pesan `user` yang ditambahkan dalam permintaan ini. | | `assistant` | Lewati penyimpanan pesan `assistant` yang ditambahkan dalam permintaan ini. | | `output` | Lewati penyimpanan pesan assistant yang dihasilkan oleh permintaan ini. | ### Permintaan Roleplay Dasar ```javascript const response = await fetch('https://api.flaq.ai/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen-plus-character', stream: false, max_tokens: 1200, temperature: 0.8, messages: [ { role: 'system', content: 'You are Jiang Rang, a witty high-school Go prodigy. Stay playful, warm, and concise.' }, { role: 'user', content: 'Why are you reading Go records outside the milk tea shop again?' } ] }) }); ``` ### Permintaan Memori Jangka Panjang ```javascript const response = await fetch('https://api.flaq.ai/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'text/event-stream', 'Content-Type': 'application/json', 'x-session': 'your-session-id' }, body: JSON.stringify({ model: 'qwen-plus-character', messages: [ { role: 'system', content: 'You are a witty high-school student who speaks with humor and warmth.' }, { role: 'user', content: 'Remember that I prefer lightly sweet milk tea.' } ], stream: true, max_tokens: 1200, temperature: 0.8, seed: 12345, profile: 'You are a witty high-school student who remembers user preferences and stays in character.', enable_long_term_memory: true, memory_entries: 50, skip_save_types: [] }) }); ``` ### Simulasi Chat Grup dengan `partial` Simulasi chat grup diimplementasikan melalui teks pesan. API tidak otomatis menetapkan atau memigrasikan nama pembicara. Tulis setiap nama pembicara secara manual di awal `content`, lalu tambahkan pesan assistant terakhir dengan prefiks pembicara target dan `partial: true`. ```javascript const response = await fetch('https://api.flaq.ai/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen-plus-character', stream: false, max_tokens: 800, temperature: 0.8, messages: [ { role: 'system', content: 'In a musician group chat, Ling Lu is a 25-year-old gifted musician known for sharp humor and a regional accent. Cheng Yi is his music partner, Tao Le is his partner, and Ma Hui is a friend. Keep Ling Lu sarcastic but caring. Reply in one short message.' }, { role: 'user', content: 'Cheng Yi: Are you free this weekend? I want feedback on the new song.' }, { role: 'user', content: 'Tao Le: He is right, but do not stay up too late editing.' }, { role: 'user', content: 'Ma Hui: Let us grab dinner and talk. My treat.' }, { role: 'assistant', content: 'Ling Lu:', partial: true } ] }) }); ``` ### Melanjutkan sebagai Karakter dengan `partial` Gunakan pola `partial` yang sama saat pengguna belum membalas tetapi Anda ingin karakter terus berbicara. Tambahkan pesan assistant terakhir dengan prefiks karakter. ```javascript { model: 'qwen-plus-character', stream: false, messages: [ { role: 'system', content: 'You are Jiang Rang, a high-school Go prodigy. Speak with humor and warmth.' }, { role: 'assistant', content: 'Class monitor, what are you doing?' }, { role: 'assistant', content: '(He waves at you.) Did being class monitor make you forget how to answer me?' }, { role: 'assistant', content: 'Jiang Rang:', partial: true } ] } ``` ## Qwen Flash Character ### Parameter Permintaan Protokol yang sama dengan Qwen Plus Character, dengan perbedaan berikut: | Parameter | Qwen Flash Character | |-----------|----------------------| | `model` | Harus berupa `"qwen-flash-character"` | ### Contoh Permintaan ```javascript { model: 'qwen-flash-character', messages: [ { role: 'system', content: 'You are a calm library assistant who speaks briefly and vividly.' }, { role: 'user', content: 'Introduce yourself in three sentences.' } ], stream: true, max_tokens: 800, temperature: 0.7, seed: 12345 } ``` ## Format Respons Model LLM Qwen Character mengembalikan respons completion yang kompatibel dengan OpenAI. Dengan `stream: true`, respons berupa Server-Sent Events; dengan `stream: false`, respons berupa satu objek JSON. ## Praktik Terbaik - Letakkan instruksi persona tingkat permintaan di pesan `system`. - Letakkan latar belakang karakter yang dapat digunakan ulang di `profile` hanya saat memori jangka panjang diaktifkan. - Gunakan kembali nilai `x-session` yang sama di percakapan terkait saat memori jangka panjang diaktifkan. Sesi yang tidak digunakan selama 365 hari dapat dihapus. - Tetap kirim pesan percakapan terbaru saat berguna; memori jangka panjang dan konteks jangka pendek dapat bekerja bersama. - Untuk simulasi chat grup, tulis nama pembicara secara manual di `content`. API tidak akan menyimpulkan nama dari `profile`. - Gunakan `partial: true` hanya pada pesan assistant terakhir saat model harus melanjutkan dari sebuah prefiks. - Gunakan Qwen Flash Character untuk roleplay ringan dan Qwen Plus Character untuk kualitas dialog yang lebih kaya.