# Qwen Character API Полный справочник API для моделей ролевого общения Qwen Character от Alibaba. Модели Qwen Character используют эндпоинт chat completions Flaq AI, но также поддерживают поля, специфичные для персонажей: долгосрочную память, симуляцию группового чата и частичное продолжение 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` | Обязательно | Используйте `text/event-stream`, когда `stream` равен `true`; используйте `application/json`, когда `stream` равен `false`. | | `x-session` | Обязательно, когда долгосрочная память включена | Пользовательский ID сессии для изоляции и вспоминания долгосрочной памяти. Память изолируется по пользовательскому ключу, поэтому разные пользователи могут использовать один и тот же ID сессии без совместного доступа к памяти. | #### Поддержка сообщений | Поле | Текст | Файл | Изображение | |-------|------|------|-------| | `messages` | Обязательно ✅ | Не поддерживается ❌ | Не поддерживается ❌ | #### Поля сообщений | Поле | Тип | Обязательно | Описание | |-------|------|----------|-------------| | `role` | string | Обязательно | Поддерживает `system`, `user` и `assistant`. | | `content` | string | Обязательно | Текст сообщения. Для симуляции группового чата вручную добавляйте имя говорящего в начало, например `Ling Lu:`. | | `partial` | boolean | Необязательно | Используется только в финальном сообщении assistant. Установите `true`, когда `content` является префиксом, от которого модель должна продолжить. | #### Необязательные | Параметр | Тип | Диапазон | Описание | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | Максимальное число выходных токенов. | | `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 | — | Количество записей памяти, которые нужно вспомнить или сохранить для сессии. В официальной документации сейчас не указано фиксированное ограничение диапазона. | | `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 возвращают ответы completion, совместимые с OpenAI. При `stream: true` ответ передаётся в формате Server-Sent Events; при `stream: false` ответ представляет собой один JSON-объект. ## Лучшие практики - Помещайте инструкции персонажа уровня запроса в сообщения `system`. - Помещайте повторно используемый фон персонажа в `profile` только когда долгосрочная память включена. - Повторно используйте одно и то же значение `x-session` в связанных разговорах, когда долгосрочная память включена. Сессии, не использованные в течение 365 дней, могут быть очищены. - Продолжайте отправлять недавние сообщения разговора, когда это полезно; долгосрочная память и краткосрочный контекст могут работать вместе. - Для симуляции группового чата вручную пишите имена говорящих в `content`. API не будет выводить имена из `profile`. - Используйте `partial: true` только в финальном сообщении assistant, когда модель должна продолжить с префикса. - Используйте Qwen Flash Character для легкого ролевого общения и Qwen Plus Character для более богатого качества диалога.