# Qwen Character API 阿里巴巴 Qwen Character 角色扮演模型的完整 API 參考。Qwen Character 模型使用 Flaq AI chat completions 端點,但也支援長期記憶、群聊模擬和 assistant 部分續寫等角色專用欄位。 ## 模型變體 此 API 支援兩種模型變體: | 模型 | ID | 描述 | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | 更高品質的角色扮演 | | **Qwen Flash Character** | `qwen-flash-character` | 更快、更實惠的角色扮演 | ## 快速比較 | 功能 | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | 文字輸入 | 必需 ✅ | 必需 ✅ | | 圖像輸入 | 不支援 ❌ | 不支援 ❌ | | 長期記憶 | 可選 | 可選 | | `temperature` | 可選 | 可選 | | `seed` | 可選 | 可選 | | 串流回應 | SSE | SSE | ## 角色扮演如何運作 單角色扮演可使用一般的 `system`、`user` 和 `assistant` 訊息。將目前請求的穩定人設指令放在 `system` 訊息中。啟用長期記憶時,將可重用的角色設定放在 `profile`。 對於群聊模擬,Qwen Character 不會自動從 `profile` 推斷說話人名稱。呼叫方必須在每則訊息 `content` 的起始位置手動寫入說話人名稱,例如 `Cheng Yi:` 或 `Ling Lu:`。若要讓模型以特定角色繼續回覆,請追加最後一則 assistant 訊息,將 `content` 設為目標說話人的前綴,並設定 `partial: true`。 `partial` 是最後一則 assistant 訊息上的訊息層級欄位。它不是頂層請求參數。 ## Qwen Plus Character ### 端點 ```http POST /api/v1/chat/completions ``` ### 請求參數 #### 必需 | 參數 | 類型 | 描述 | |-----------|------|-------------| | `model` | string | 必須為 `"qwen-plus-character"` | | `messages` | array | 包含 `system`、`user` 和可選 `assistant` 角色的有序訊息。 | | `stream` | boolean | `true` 表示 SSE,`false` 表示單一 JSON 回應。 | #### 標頭 | 標頭 | 必需 | 描述 | |--------|----------|-------------| | `Authorization` | 必需 | API 金鑰,格式為 `Bearer YOUR_API_KEY`。 | | `Content-Type` | 必需 | 使用 `application/json`。 | | `Accept` | 必需 | 當 `stream` 為 `true` 時使用 `text/event-stream`;當 `stream` 為 `false` 時使用 `application/json`。 | | `x-session` | 啟用長期記憶時必需 | 使用者自訂的 session ID,用於長期記憶隔離與回憶。記憶會按使用者 key 隔離,因此不同使用者可重複使用相同 session ID,而不會共享記憶。 | #### 訊息支援 | 欄位 | 文字 | 檔案 | 圖像 | |-------|------|------|-------| | `messages` | 必需 ✅ | 不支援 ❌ | 不支援 ❌ | #### 訊息欄位 | 欄位 | 類型 | 必需 | 描述 | |-------|------|----------|-------------| | `role` | string | 必需 | 支援 `system`、`user` 和 `assistant`。 | | `content` | string | 必需 | 訊息文字。對於群聊模擬,請在開頭手動加入說話人名稱,例如 `Ling Lu:`。 | | `partial` | boolean | 可選 | 只用於最後一則 assistant 訊息。當 `content` 是模型應該從中繼續的前綴時,設定為 `true`。 | #### 可選 | 參數 | 類型 | 範圍 | 描述 | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | 最大輸出 token 數。 | | `temperature` | number | `0.0` - `1.0` | 控制回應隨機性。 | | `seed` | integer | `0` - `2147483647` | 用於可重現輸出的隨機種子。它與對話上下文視窗無關。 | | `profile` | string | — | 角色設定。當 `enable_long_term_memory` 為 `true` 時必需。`profile` 不會自動為訊息加入說話人名稱。 | | `enable_long_term_memory` | boolean | — | 為本次請求啟用長期記憶。需要 `profile` 和 `x-session` 標頭。 | | `memory_entries` | integer | — | 要為 session 回憶或保留的記憶項目數量。目前官方文件未公開固定範圍限制。 | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | 本次請求要略過儲存的記憶類型。 | 啟用長期記憶時,你必須提供: - `x-session` 請求標頭 - 請求主體中的 `profile` - `enable_long_term_memory: true` `skip_save_types` 支援以下值: | 值 | 含義 | |-------|---------| | `system` | 略過儲存本次請求中新增的 `system` 訊息。 | | `user` | 略過儲存本次請求中新增的 `user` 訊息。 | | `assistant` | 略過儲存本次請求中新增的 `assistant` 訊息。 | | `output` | 略過儲存本次請求生成的 assistant 訊息。 | ### 基本角色扮演請求 ```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?' } ] }) }); ``` ### 長期記憶請求 ```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: [] }) }); ``` ### 使用 `partial` 進行群聊模擬 群聊模擬透過訊息文字實現。API 不會自動指派或遷移說話人名稱。請在 `content` 開頭手動寫入每個說話人名稱,然後追加最後一則 assistant 訊息,帶上目標說話人的前綴和 `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 } ] }) }); ``` ### 使用 `partial` 以角色身份繼續 當使用者尚未回覆,但你希望角色繼續說話時,也可使用相同的 `partial` 模式。加入最後一則 assistant 訊息,內容為角色前綴。 ```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 ### 請求參數 協定與 Qwen Plus Character 相同,差異如下: | 參數 | Qwen Flash Character | |-----------|----------------------| | `model` | 必須為 `"qwen-flash-character"` | ### 請求範例 ```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 } ``` ## 回應格式 Qwen Character LLM 模型會傳回與 OpenAI 相容的補全回應。使用 `stream: true` 時,回應為伺服器傳送事件(SSE);使用 `stream: false` 時,回應為單一 JSON 物件。 ## 最佳實務 - 將請求層級的人設指令放在 `system` 訊息中。 - 只有在啟用長期記憶時,才將可重用的角色背景放在 `profile`。 - 啟用長期記憶時,請在相關對話中重用相同的 `x-session` 值。365 天未使用的 session 可能會被清除。 - 有用時繼續傳送最近的對話訊息;長期記憶和短期上下文可以一起使用。 - 對於群聊模擬,請在 `content` 中手動寫入說話人名稱。API 不會從 `profile` 推斷名稱。 - 只有當模型應從某個前綴繼續時,才在最後一則 assistant 訊息中使用 `partial: true`。 - 使用 Qwen Flash Character 處理輕量級角色扮演,使用 Qwen Plus Character 取得更豐富的對話品質。