# API Qwen Character Riferimento API completo per i modelli di roleplay Qwen Character di Alibaba. I modelli Qwen Character usano l'endpoint chat completions di Flaq AI, ma supportano anche campi specifici per personaggi per memoria a lungo termine, simulazione di chat di gruppo e continuazione parziale dell'assistente. ## Varianti del modello Questa API supporta due varianti del modello: | Modello | ID | Descrizione | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | Roleplay di personaggi di qualità superiore | | **Qwen Flash Character** | `qwen-flash-character` | Roleplay di personaggi più rapido e conveniente | ## Confronto rapido | Funzionalità | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | Input di testo | Obbligatorio ✅ | Obbligatorio ✅ | | Input immagine | Non supportato ❌ | Non supportato ❌ | | Memoria a lungo termine | Opzionale | Opzionale | | `temperature` | Opzionale | Opzionale | | `seed` | Opzionale | Opzionale | | Risposta in streaming | SSE | SSE | ## Come funziona il roleplay dei personaggi Usa normali messaggi `system`, `user` e `assistant` per il roleplay con un singolo personaggio. Inserisci le istruzioni di persona stabili in un messaggio `system` per la richiesta corrente. Quando la memoria a lungo termine è abilitata, inserisci il profilo riutilizzabile del personaggio in `profile`. Per la simulazione di chat di gruppo, Qwen Character non deduce automaticamente i nomi dei parlanti da `profile`. Il chiamante deve scrivere i nomi dei parlanti all'inizio di ogni `content` del messaggio, ad esempio `Cheng Yi:` o `Ling Lu:`. Per far continuare il modello come un personaggio specifico, aggiungi un messaggio finale assistant il cui `content` sia il prefisso del parlante di destinazione e imposta `partial: true`. `partial` è un campo a livello di messaggio sul messaggio finale assistant. Non è un parametro di richiesta di primo livello. ## Qwen Plus Character ### Punto di accesso ```http POST /api/v1/chat/completions ``` ### Parametri della richiesta #### Obbligatori | Parametro | Tipo | Descrizione | |-----------|------|-------------| | `model` | string | Deve essere `"qwen-plus-character"` | | `messages` | array | Messaggi ordinati con ruoli `system`, `user` e facoltativamente `assistant`. | | `stream` | boolean | `true` per SSE, `false` per una singola risposta JSON. | #### Header | Header | Obbligatorio | Descrizione | |--------|----------|-------------| | `Authorization` | Obbligatorio | Chiave API, nel formato `Bearer YOUR_API_KEY`. | | `Content-Type` | Obbligatorio | Usa `application/json`. | | `Accept` | Obbligatorio | Usa `text/event-stream` quando `stream` è `true`; usa `application/json` quando `stream` è `false`. | | `x-session` | Obbligatorio quando la memoria a lungo termine è abilitata | ID sessione definito dall'utente per isolamento e richiamo della memoria a lungo termine. La memoria è isolata per chiave utente, quindi utenti diversi possono riutilizzare lo stesso ID sessione senza condividere memoria. | #### Supporto messaggi | Campo | Testo | File | Immagine | |-------|------|------|-------| | `messages` | Obbligatorio ✅ | Non supportato ❌ | Non supportata ❌ | #### Campi dei messaggi | Campo | Tipo | Obbligatorio | Descrizione | |-------|------|----------|-------------| | `role` | string | Obbligatorio | Supporta `system`, `user` e `assistant`. | | `content` | string | Obbligatorio | Testo del messaggio. Per la simulazione di chat di gruppo, includi manualmente il nome del parlante all'inizio, ad esempio `Ling Lu:`. | | `partial` | boolean | Opzionale | Usato solo sul messaggio finale assistant. Impostalo su `true` quando `content` è un prefisso da cui il modello deve continuare. | #### Opzionali | Parametro | Tipo | Intervallo | Descrizione | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | Token di output massimi. | | `temperature` | number | `0.0` - `1.0` | Controlla la casualità della risposta. | | `seed` | integer | `0` - `2147483647` | Seed casuale per output riproducibile. Non è correlato alla finestra di contesto della conversazione. | | `profile` | string | — | Profilo del personaggio. Obbligatorio quando `enable_long_term_memory` è `true`. `profile` non aggiunge automaticamente i nomi dei parlanti ai messaggi. | | `enable_long_term_memory` | boolean | — | Abilita la memoria a lungo termine per la richiesta. Richiede `profile` e l'header `x-session`. | | `memory_entries` | integer | — | Numero di voci di memoria da richiamare o conservare per la sessione. La documentazione ufficiale attualmente non espone un limite di intervallo fisso. | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | Tipi di memoria da non salvare per questa richiesta. | Quando la memoria a lungo termine è abilitata, devi fornire: - Header di richiesta `x-session` - `profile` nel corpo della richiesta - `enable_long_term_memory: true` `skip_save_types` supporta questi valori: | Valore | Significato | |-------|---------| | `system` | Salta il salvataggio dei messaggi `system` aggiunti in questa richiesta. | | `user` | Salta il salvataggio dei messaggi `user` aggiunti in questa richiesta. | | `assistant` | Salta il salvataggio dei messaggi `assistant` aggiunti in questa richiesta. | | `output` | Salta il salvataggio del messaggio assistant generato da questa richiesta. | ### Richiesta di roleplay di base ```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?' } ] }) }); ``` ### Richiesta con memoria a lungo termine ```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: [] }) }); ``` ### Simulazione di chat di gruppo con `partial` La simulazione di chat di gruppo è implementata tramite il testo dei messaggi. L'API non assegna né migra automaticamente i nomi dei parlanti. Scrivi ogni nome di parlante manualmente all'inizio di `content`, poi aggiungi un messaggio finale assistant con il prefisso del parlante di destinazione 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 } ] }) }); ``` ### Continuare come personaggio con `partial` Usa lo stesso schema `partial` quando l'utente non ha risposto ma vuoi che il personaggio continui a parlare. Aggiungi un messaggio finale assistant con il prefisso del personaggio. ```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 ### Parametri della richiesta Stesso protocollo di Qwen Plus Character, con queste differenze: | Parametro | Qwen Flash Character | |-----------|----------------------| | `model` | Deve essere `"qwen-flash-character"` | ### Richiesta di esempio ```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 della risposta I modelli LLM Qwen Character restituiscono risposte di completamento compatibili con OpenAI. Con `stream: true`, la risposta viene trasmessa tramite eventi inviati dal server (SSE); con `stream: false`, viene restituita come un singolo oggetto JSON. ## Buone pratiche - Inserisci le istruzioni di persona a livello di richiesta nei messaggi `system`. - Inserisci il background riutilizzabile del personaggio in `profile` solo quando la memoria a lungo termine è abilitata. - Riutilizza lo stesso valore `x-session` nelle conversazioni correlate quando la memoria a lungo termine è abilitata. Le sessioni inutilizzate per 365 giorni possono essere eliminate. - Continua a inviare i messaggi recenti della conversazione quando è utile; memoria a lungo termine e contesto a breve termine possono funzionare insieme. - Per la simulazione di chat di gruppo, scrivi manualmente i nomi dei parlanti in `content`. L'API non dedurrà i nomi da `profile`. - Usa `partial: true` solo sul messaggio finale assistant quando il modello deve continuare da un prefisso. - Usa Qwen Flash Character per roleplay leggero e Qwen Plus Character per una qualità di dialogo più ricca.