# Qwen Character API Complete API reference for Qwen Character roleplay models by Alibaba. Qwen Character models use the Flaq AI chat completions endpoint, but they also support character-specific fields for long-term memory, group-chat simulation, and partial assistant continuation. ## Model Variants This API supports two model variants: | Model | ID | Description | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | Higher-quality character roleplay | | **Qwen Flash Character** | `qwen-flash-character` | Faster, more affordable character roleplay | ## Quick Comparison | Feature | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | Text input | Required ✅ | Required ✅ | | Image input | Not supported ❌ | Not supported ❌ | | Long-term memory | Optional | Optional | | `temperature` | Optional | Optional | | `seed` | Optional | Optional | | Streaming response | SSE | SSE | ## How Character Roleplay Works Use normal `system`, `user`, and `assistant` messages for single-character roleplay. Put stable persona instructions in a `system` message for the current request. When long-term memory is enabled, put the reusable character profile in `profile`. For group-chat simulation, Qwen Character does not automatically infer speaker names from `profile`. The caller must write speaker names at the beginning of each message `content`, such as `Cheng Yi:` or `Ling Lu:`. To make the model continue as a specific character, append a final assistant message whose `content` is the target speaker prefix and set `partial: true`. `partial` is a message-level field on the final assistant message. It is not a top-level request parameter. ## Qwen Plus Character ### Endpoint ```http POST /api/v1/chat/completions ``` ### Request Parameters #### Required | Parameter | Type | Description | |-----------|------|-------------| | `model` | string | Must be `"qwen-plus-character"` | | `messages` | array | Ordered messages with `system`, `user`, and optional `assistant` roles. | | `stream` | boolean | `true` for SSE, `false` for a single JSON response. | #### Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Required | API key, formatted as `Bearer YOUR_API_KEY`. | | `Content-Type` | Required | Use `application/json`. | | `Accept` | Required | Use `text/event-stream` when `stream` is `true`; use `application/json` when `stream` is `false`. | | `x-session` | Required when long-term memory is enabled | User-defined session ID for long-term memory isolation and recall. Memory is isolated by user key, so different users can reuse the same session ID without sharing memory. | #### Message Support | Field | Text | File | Image | |-------|------|------|-------| | `messages` | Required ✅ | Not supported ❌ | Not supported ❌ | #### Message Fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `role` | string | Required | Supports `system`, `user`, and `assistant`. | | `content` | string | Required | Message text. For group-chat simulation, include the speaker name manually at the start, such as `Ling Lu:`. | | `partial` | boolean | Optional | Only used on the final assistant message. Set to `true` when `content` is a prefix that the model should continue from. | #### Optional | Parameter | Type | Range | Description | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | Maximum output tokens. | | `temperature` | number | `0.0` - `1.0` | Controls response randomness. | | `seed` | integer | `0` - `2147483647` | Random seed for reproducible output. It is unrelated to the conversation context window. | | `profile` | string | — | Character profile. Required when `enable_long_term_memory` is `true`. `profile` does not automatically add speaker names to messages. | | `enable_long_term_memory` | boolean | — | Enables long-term memory for the request. Requires `profile` and the `x-session` header. | | `memory_entries` | integer | — | Number of memory entries to recall or keep for the session. No fixed range limit is currently exposed by the official docs. | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | Memory types to skip saving for this request. | When long-term memory is enabled, you must provide: - `x-session` request header - `profile` in the request body - `enable_long_term_memory: true` `skip_save_types` supports these values: | Value | Meaning | |-------|---------| | `system` | Skip saving `system` messages added in this request. | | `user` | Skip saving `user` messages added in this request. | | `assistant` | Skip saving `assistant` messages added in this request. | | `output` | Skip saving the assistant message generated by this request. | ### Basic Roleplay Request ```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?' } ] }) }); ``` ### Long-Term Memory Request ```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: [] }) }); ``` ### Group Chat Simulation with `partial` Group-chat simulation is implemented through message text. The API does not automatically assign or migrate speaker names. Write each speaker name manually at the start of `content`, then append a final assistant message with the target speaker prefix and `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 } ] }) }); ``` ### Continue as Character with `partial` Use the same `partial` pattern when the user has not replied but you want the character to continue speaking. Add a final assistant message with the character prefix. ```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 ### Request Parameters Same protocol as Qwen Plus Character, with these differences: | Parameter | Qwen Flash Character | |-----------|----------------------| | `model` | Must be `"qwen-flash-character"` | ### Example Request ```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 } ``` ## Response Format Qwen Character LLM models return OpenAI-compatible completion responses. With `stream: true`, the response is Server-Sent Events; with `stream: false`, the response is a single JSON object. ## Best Practices - Put request-level persona instructions in `system` messages. - Put reusable character background in `profile` only when long-term memory is enabled. - Reuse the same `x-session` value across related conversations when long-term memory is enabled. Sessions unused for 365 days may be cleared. - Continue sending recent conversation messages when useful; long-term memory and short-term context can work together. - For group-chat simulation, manually write speaker names in `content`. The API will not infer names from `profile`. - Use `partial: true` only on the final assistant message when the model should continue from a prefix. - Use Qwen Flash Character for lightweight roleplay and Qwen Plus Character for richer dialogue quality.