# API Qwen Character Referência completa da API para modelos de roleplay Qwen Character da Alibaba. Os modelos Qwen Character usam o endpoint de chat completions da Flaq AI, mas também oferecem suporte a campos específicos de personagem para memória de longo prazo, simulação de chat em grupo e continuação parcial do assistant. ## Variantes do modelo Esta API oferece suporte a duas variantes de modelo: | Modelo | ID | Descrição | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | Roleplay de personagem com maior qualidade | | **Qwen Flash Character** | `qwen-flash-character` | Roleplay de personagem mais rápido e acessível | ## Comparação rápida | Recurso | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | Entrada de texto | Obrigatória ✅ | Obrigatória ✅ | | Entrada de imagem | Não compatível ❌ | Não compatível ❌ | | Memória de longo prazo | Opcional | Opcional | | `temperature` | Opcional | Opcional | | `seed` | Opcional | Opcional | | Resposta em streaming | SSE | SSE | ## Como funciona o roleplay de personagens Use mensagens normais `system`, `user` e `assistant` para roleplay com um único personagem. Coloque instruções estáveis de persona em uma mensagem `system` para a solicitação atual. Quando a memória de longo prazo estiver habilitada, coloque o perfil reutilizável do personagem em `profile`. Para simulação de chat em grupo, Qwen Character não infere automaticamente os nomes dos falantes a partir de `profile`. O chamador deve escrever os nomes dos falantes no início de cada `content` de mensagem, como `Cheng Yi:` ou `Ling Lu:`. Para fazer o modelo continuar como um personagem específico, adicione uma mensagem final de assistant cujo `content` seja o prefixo do falante de destino e defina `partial: true`. `partial` é um campo no nível da mensagem na mensagem final de assistant. Ele não é um parâmetro de solicitação de nível superior. ## Qwen Plus Character ### Ponto de conexão ```http POST /api/v1/chat/completions ``` ### Parâmetros da solicitação #### Obrigatórios | Parâmetro | Tipo | Descrição | |-----------|------|-------------| | `model` | string | Deve ser `"qwen-plus-character"` | | `messages` | array | Mensagens ordenadas com funções `system`, `user` e `assistant` opcional. | | `stream` | boolean | `true` para SSE, `false` para uma única resposta JSON. | #### Cabeçalhos | Cabeçalho | Obrigatório | Descrição | |--------|----------|-------------| | `Authorization` | Obrigatório | Chave de API, formatada como `Bearer YOUR_API_KEY`. | | `Content-Type` | Obrigatório | Use `application/json`. | | `Accept` | Obrigatório | Use `text/event-stream` quando `stream` for `true`; use `application/json` quando `stream` for `false`. | | `x-session` | Obrigatório quando a memória de longo prazo está habilitada | ID de sessão definido pelo usuário para isolamento e recuperação da memória de longo prazo. A memória é isolada por chave de usuário, portanto usuários diferentes podem reutilizar o mesmo ID de sessão sem compartilhar memória. | #### Suporte a mensagens | Campo | Texto | Arquivo | Imagem | |-------|------|------|-------| | `messages` | Obrigatório ✅ | Não compatível ❌ | Não compatível ❌ | #### Campos de mensagem | Campo | Tipo | Obrigatório | Descrição | |-------|------|----------|-------------| | `role` | string | Obrigatório | Oferece suporte a `system`, `user` e `assistant`. | | `content` | string | Obrigatório | Texto da mensagem. Para simulação de chat em grupo, inclua manualmente o nome do falante no início, como `Ling Lu:`. | | `partial` | boolean | Opcional | Usado apenas na mensagem final de assistant. Defina como `true` quando `content` for um prefixo do qual o modelo deve continuar. | #### Opcionais | Parâmetro | Tipo | Intervalo | Descrição | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | Máximo de tokens de saída. | | `temperature` | number | `0.0` - `1.0` | Controla a aleatoriedade da resposta. | | `seed` | integer | `0` - `2147483647` | Seed aleatório para saída reproduzível. Ele não está relacionado à janela de contexto da conversa. | | `profile` | string | — | Perfil do personagem. Obrigatório quando `enable_long_term_memory` é `true`. `profile` não adiciona automaticamente nomes de falantes às mensagens. | | `enable_long_term_memory` | boolean | — | Habilita memória de longo prazo para a solicitação. Requer `profile` e o cabeçalho `x-session`. | | `memory_entries` | integer | — | Número de entradas de memória a recuperar ou manter para a sessão. Atualmente, a documentação oficial não expõe um limite fixo de intervalo. | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | Tipos de memória para ignorar o salvamento nesta solicitação. | Quando a memória de longo prazo está habilitada, você deve fornecer: - Cabeçalho de solicitação `x-session` - `profile` no corpo da solicitação - `enable_long_term_memory: true` `skip_save_types` oferece suporte a estes valores: | Valor | Significado | |-------|---------| | `system` | Ignora o salvamento de mensagens `system` adicionadas nesta solicitação. | | `user` | Ignora o salvamento de mensagens `user` adicionadas nesta solicitação. | | `assistant` | Ignora o salvamento de mensagens `assistant` adicionadas nesta solicitação. | | `output` | Ignora o salvamento da mensagem de assistant gerada por esta solicitação. | ### Solicitação básica de roleplay ```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?' } ] }) }); ``` ### Solicitação com memória de longo prazo ```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: [] }) }); ``` ### Simulação de chat em grupo com `partial` A simulação de chat em grupo é implementada por meio do texto das mensagens. A API não atribui nem migra automaticamente nomes de falantes. Escreva cada nome de falante manualmente no início de `content` e depois adicione uma mensagem final de assistant com o prefixo do falante de destino e `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 } ] }) }); ``` ### Continuar como personagem com `partial` Use o mesmo padrão de `partial` quando o usuário não tiver respondido, mas você quiser que o personagem continue falando. Adicione uma mensagem final de assistant com o prefixo do personagem. ```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 ### Parâmetros da solicitação Mesmo protocolo que Qwen Plus Character, com estas diferenças: | Parâmetro | Qwen Flash Character | |-----------|----------------------| | `model` | Deve ser `"qwen-flash-character"` | ### Solicitação de exemplo ```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 } ``` ## Formato da resposta Os modelos LLM Qwen Character retornam respostas de conclusão compatíveis com a OpenAI. Com `stream: true`, a resposta é transmitida por eventos enviados pelo servidor (SSE); com `stream: false`, ela é retornada como um único objeto JSON. ## Boas práticas - Coloque instruções de persona no nível da solicitação em mensagens `system`. - Coloque o histórico reutilizável do personagem em `profile` somente quando a memória de longo prazo estiver habilitada. - Reutilize o mesmo valor de `x-session` em conversas relacionadas quando a memória de longo prazo estiver habilitada. Sessões sem uso por 365 dias podem ser apagadas. - Continue enviando mensagens recentes da conversa quando for útil; memória de longo prazo e contexto de curto prazo podem funcionar juntos. - Para simulação de chat em grupo, escreva manualmente os nomes dos falantes em `content`. A API não inferirá nomes de `profile`. - Use `partial: true` somente na mensagem final de assistant quando o modelo deve continuar a partir de um prefixo. - Use Qwen Flash Character para roleplay leve e Qwen Plus Character para qualidade de diálogo mais rica.