# API de Qwen Character Referencia completa de la API para los modelos de roleplay Qwen Character de Alibaba. Los modelos Qwen Character usan el endpoint de chat completions de Flaq AI, pero también admiten campos específicos de personaje para memoria a largo plazo, simulación de chat grupal y continuación parcial del asistente. ## Variantes del modelo Esta API admite dos variantes de modelo: | Modelo | ID | Descripción | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | Roleplay de personajes de mayor calidad | | **Qwen Flash Character** | `qwen-flash-character` | Roleplay de personajes más rápido y asequible | ## Comparación rápida | Función | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | Entrada de texto | Obligatoria ✅ | Obligatoria ✅ | | Entrada de imagen | No compatible ❌ | No compatible ❌ | | Memoria a largo plazo | Opcional | Opcional | | `temperature` | Opcional | Opcional | | `seed` | Opcional | Opcional | | Respuesta en streaming | SSE | SSE | ## Cómo funciona el roleplay de personajes Usa mensajes normales `system`, `user` y `assistant` para el roleplay de un solo personaje. Coloca las instrucciones estables de persona en un mensaje `system` para la solicitud actual. Cuando la memoria a largo plazo esté habilitada, coloca el perfil reutilizable del personaje en `profile`. Para la simulación de chat grupal, Qwen Character no infiere automáticamente los nombres de los hablantes desde `profile`. El llamador debe escribir los nombres de los hablantes al comienzo de cada `content` de mensaje, como `Cheng Yi:` o `Ling Lu:`. Para hacer que el modelo continúe como un personaje específico, agrega un mensaje final de asistente cuyo `content` sea el prefijo del hablante objetivo y establece `partial: true`. `partial` es un campo de nivel de mensaje en el mensaje final de asistente. No es un parámetro de solicitud de nivel superior. ## Qwen Plus Character ### Punto de conexión ```http POST /api/v1/chat/completions ``` ### Parámetros de solicitud #### Obligatorios | Parámetro | Tipo | Descripción | |-----------|------|-------------| | `model` | string | Debe ser `"qwen-plus-character"` | | `messages` | array | Mensajes ordenados con roles `system`, `user` y `assistant` opcional. | | `stream` | boolean | `true` para SSE, `false` para una única respuesta JSON. | #### Encabezados | Encabezado | Obligatorio | Descripción | |--------|----------|-------------| | `Authorization` | Obligatorio | Clave API, con el formato `Bearer YOUR_API_KEY`. | | `Content-Type` | Obligatorio | Usa `application/json`. | | `Accept` | Obligatorio | Usa `text/event-stream` cuando `stream` es `true`; usa `application/json` cuando `stream` es `false`. | | `x-session` | Obligatorio cuando la memoria a largo plazo está habilitada | ID de sesión definido por el usuario para aislar y recuperar memoria a largo plazo. La memoria se aísla por clave de usuario, por lo que distintos usuarios pueden reutilizar el mismo ID de sesión sin compartir memoria. | #### Compatibilidad de mensajes | Campo | Texto | Archivo | Imagen | |-------|------|------|-------| | `messages` | Obligatorio ✅ | No compatible ❌ | No compatible ❌ | #### Campos de mensaje | Campo | Tipo | Obligatorio | Descripción | |-------|------|----------|-------------| | `role` | string | Obligatorio | Admite `system`, `user` y `assistant`. | | `content` | string | Obligatorio | Texto del mensaje. Para la simulación de chat grupal, incluye manualmente el nombre del hablante al inicio, como `Ling Lu:`. | | `partial` | boolean | Opcional | Solo se usa en el mensaje final de asistente. Establécelo en `true` cuando `content` sea un prefijo desde el que el modelo debe continuar. | #### Opcionales | Parámetro | Tipo | Rango | Descripción | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | Tokens máximos de salida. | | `temperature` | number | `0.0` - `1.0` | Controla la aleatoriedad de la respuesta. | | `seed` | integer | `0` - `2147483647` | Semilla aleatoria para salida reproducible. No está relacionada con la ventana de contexto de la conversación. | | `profile` | string | — | Perfil del personaje. Obligatorio cuando `enable_long_term_memory` es `true`. `profile` no agrega automáticamente nombres de hablantes a los mensajes. | | `enable_long_term_memory` | boolean | — | Habilita la memoria a largo plazo para la solicitud. Requiere `profile` y el encabezado `x-session`. | | `memory_entries` | integer | — | Número de entradas de memoria que se recuperan o conservan para la sesión. Actualmente la documentación oficial no expone un límite de rango fijo. | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | Tipos de memoria que se omiten al guardar para esta solicitud. | Cuando la memoria a largo plazo está habilitada, debes proporcionar: - Encabezado de solicitud `x-session` - `profile` en el cuerpo de la solicitud - `enable_long_term_memory: true` `skip_save_types` admite estos valores: | Valor | Significado | |-------|---------| | `system` | Omite guardar los mensajes `system` agregados en esta solicitud. | | `user` | Omite guardar los mensajes `user` agregados en esta solicitud. | | `assistant` | Omite guardar los mensajes `assistant` agregados en esta solicitud. | | `output` | Omite guardar el mensaje de asistente generado por esta solicitud. | ### Solicitud 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?' } ] }) }); ``` ### Solicitud con memoria a largo plazo ```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: [] }) }); ``` ### Simulación de chat grupal con `partial` La simulación de chat grupal se implementa mediante el texto de los mensajes. La API no asigna ni migra automáticamente nombres de hablantes. Escribe cada nombre de hablante manualmente al inicio de `content` y luego agrega un mensaje final de asistente con el prefijo del hablante objetivo y `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 personaje con `partial` Usa el mismo patrón de `partial` cuando el usuario no haya respondido pero quieras que el personaje siga hablando. Agrega un mensaje final de asistente con el prefijo del personaje. ```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 de solicitud El mismo protocolo que Qwen Plus Character, con estas diferencias: | Parámetro | Qwen Flash Character | |-----------|----------------------| | `model` | Debe ser `"qwen-flash-character"` | ### Solicitud de ejemplo ```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 de respuesta Los modelos LLM Qwen Character devuelven respuestas de finalización compatibles con OpenAI. Con `stream: true`, la respuesta se transmite mediante eventos enviados por el servidor (SSE); con `stream: false`, se devuelve como un único objeto JSON. ## Buenas prácticas - Coloca las instrucciones de persona de nivel de solicitud en mensajes `system`. - Coloca el trasfondo reutilizable del personaje en `profile` solo cuando la memoria a largo plazo esté habilitada. - Reutiliza el mismo valor de `x-session` en conversaciones relacionadas cuando la memoria a largo plazo esté habilitada. Las sesiones sin uso durante 365 días pueden borrarse. - Sigue enviando mensajes recientes de la conversación cuando sea útil; la memoria a largo plazo y el contexto a corto plazo pueden funcionar juntos. - Para la simulación de chat grupal, escribe manualmente los nombres de los hablantes en `content`. La API no inferirá nombres desde `profile`. - Usa `partial: true` solo en el mensaje final de asistente cuando el modelo deba continuar desde un prefijo. - Usa Qwen Flash Character para roleplay ligero y Qwen Plus Character para una calidad de diálogo más rica.