# Qwen Character API 阿里巴巴 Qwen Character 角色扮演模型的完整 API 参考。Qwen Character 模型使用 Flaq AI chat completions 端点,同时也支持长期记忆、群聊模拟和 assistant partial 续写等角色专属字段。 ## 模型变体 此 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 key,格式为 `Bearer YOUR_API_KEY`。 | | `Content-Type` | 必需 | 使用 `application/json`。 | | `Accept` | 必需 | 当 `stream` 为 `true` 时使用 `text/event-stream`;当 `stream` 为 `false` 时使用 `application/json`。 | | `x-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 | — | 本次请求或会话使用的长期记忆条数。官方文档当前没有暴露固定范围限制。 | | `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` 开头手动写入说话人名,然后追加一条带目标说话人前缀和 `partial: true` 的最终 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: 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 获得更丰富的对话质量。