# Qwen Character API Vollständige API-Referenz für Qwen Character Rollenspielmodelle von Alibaba. Qwen Character Modelle verwenden den Chat-Completions-Endpunkt von Flaq AI, unterstützen aber zusätzlich charakterspezifische Felder für Langzeitgedächtnis, Gruppenchat-Simulation und partielle Assistant-Fortsetzung. ## Modellvarianten Diese API unterstützt zwei Modellvarianten: | Modell | ID | Beschreibung | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | Hochwertigeres Charakter-Rollenspiel | | **Qwen Flash Character** | `qwen-flash-character` | Schnelleres und günstigeres Charakter-Rollenspiel | ## Schneller Vergleich | Funktion | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | Texteingabe | Erforderlich ✅ | Erforderlich ✅ | | Bildeingabe | Nicht unterstützt ❌ | Nicht unterstützt ❌ | | Langzeitgedächtnis | Optional | Optional | | `temperature` | Optional | Optional | | `seed` | Optional | Optional | | Streaming-Antwort | SSE | SSE | ## Funktionsweise des Charakter-Rollenspiels Verwenden Sie normale `system`-, `user`- und `assistant`-Nachrichten für Rollenspiele mit einem einzelnen Charakter. Legen Sie stabile Persona-Anweisungen für die aktuelle Anfrage in einer `system`-Nachricht ab. Wenn Langzeitgedächtnis aktiviert ist, legen Sie das wiederverwendbare Charakterprofil in `profile` ab. Für die Gruppenchat-Simulation leitet Qwen Character Sprechernamen nicht automatisch aus `profile` ab. Der Aufrufer muss Sprechernamen am Anfang jedes Nachrichten-`content` schreiben, etwa `Cheng Yi:` oder `Ling Lu:`. Damit das Modell als bestimmter Charakter fortfährt, hängen Sie eine abschließende Assistant-Nachricht an, deren `content` das Zielsprecher-Präfix ist, und setzen Sie `partial: true`. `partial` ist ein Feld auf Nachrichtenebene in der abschließenden Assistant-Nachricht. Es ist kein Anfrageparameter auf oberster Ebene. ## Qwen Plus Character ### Endpunkt ```http POST /api/v1/chat/completions ``` ### Anfrageparameter #### Erforderlich | Parameter | Typ | Beschreibung | |-----------|------|-------------| | `model` | string | Muss `"qwen-plus-character"` sein | | `messages` | array | Geordnete Nachrichten mit den Rollen `system`, `user` und optional `assistant`. | | `stream` | boolean | `true` für SSE, `false` für eine einzelne JSON-Antwort. | #### Header | Header | Erforderlich | Beschreibung | |--------|----------|-------------| | `Authorization` | Erforderlich | API-Schlüssel im Format `Bearer YOUR_API_KEY`. | | `Content-Type` | Erforderlich | Verwenden Sie `application/json`. | | `Accept` | Erforderlich | Verwenden Sie `text/event-stream`, wenn `stream` `true` ist; verwenden Sie `application/json`, wenn `stream` `false` ist. | | `x-session` | Erforderlich, wenn Langzeitgedächtnis aktiviert ist | Benutzerdefinierte Sitzungs-ID zur Isolation und zum Abruf des Langzeitgedächtnisses. Speicher wird nach Benutzerschlüssel isoliert, sodass unterschiedliche Benutzer dieselbe Sitzungs-ID wiederverwenden können, ohne Speicher zu teilen. | #### Nachrichtenunterstützung | Feld | Text | Datei | Bild | |-------|------|------|-------| | `messages` | Erforderlich ✅ | Nicht unterstützt ❌ | Nicht unterstützt ❌ | #### Nachrichtenfelder | Feld | Typ | Erforderlich | Beschreibung | |-------|------|----------|-------------| | `role` | string | Erforderlich | Unterstützt `system`, `user` und `assistant`. | | `content` | string | Erforderlich | Nachrichtentext. Für die Gruppenchat-Simulation fügen Sie den Sprechernamen manuell am Anfang ein, etwa `Ling Lu:`. | | `partial` | boolean | Optional | Wird nur in der abschließenden Assistant-Nachricht verwendet. Setzen Sie es auf `true`, wenn `content` ein Präfix ist, ab dem das Modell fortfahren soll. | #### Optionale Angaben | Parameter | Typ | Bereich | Beschreibung | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | Maximale Ausgabetokens. | | `temperature` | number | `0.0` - `1.0` | Steuert die Zufälligkeit der Antwort. | | `seed` | integer | `0` - `2147483647` | Zufalls-Seed für reproduzierbare Ausgaben. Er steht nicht mit dem Kontextfenster der Unterhaltung in Zusammenhang. | | `profile` | string | — | Charakterprofil. Erforderlich, wenn `enable_long_term_memory` `true` ist. `profile` fügt Nachrichten nicht automatisch Sprechernamen hinzu. | | `enable_long_term_memory` | boolean | — | Aktiviert Langzeitgedächtnis für die Anfrage. Erfordert `profile` und den Header `x-session`. | | `memory_entries` | integer | — | Anzahl der Gedächtniseinträge, die für die Sitzung abgerufen oder behalten werden. Die offiziellen Dokumente nennen derzeit keine feste Bereichsgrenze. | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | Speichertypen, die für diese Anfrage übersprungen werden sollen. | Wenn Langzeitgedächtnis aktiviert ist, müssen Sie Folgendes angeben: - `x-session`-Anfrageheader - `profile` im Anfragebody - `enable_long_term_memory: true` `skip_save_types` unterstützt diese Werte: | Wert | Bedeutung | |-------|---------| | `system` | Überspringt das Speichern von `system`-Nachrichten, die in dieser Anfrage hinzugefügt wurden. | | `user` | Überspringt das Speichern von `user`-Nachrichten, die in dieser Anfrage hinzugefügt wurden. | | `assistant` | Überspringt das Speichern von `assistant`-Nachrichten, die in dieser Anfrage hinzugefügt wurden. | | `output` | Überspringt das Speichern der von dieser Anfrage erzeugten Assistant-Nachricht. | ### Einfache Rollenspielanfrage ```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?' } ] }) }); ``` ### Anfrage mit Langzeitgedächtnis ```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: [] }) }); ``` ### Gruppenchat-Simulation mit `partial` Die Gruppenchat-Simulation wird über Nachrichtentext umgesetzt. Die API weist Sprechernamen nicht automatisch zu und migriert sie nicht automatisch. Schreiben Sie jeden Sprechernamen manuell an den Anfang von `content` und hängen Sie anschließend eine abschließende Assistant-Nachricht mit dem Zielsprecher-Präfix und `partial: true` an. ```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 } ] }) }); ``` ### Als Charakter mit `partial` fortfahren Verwenden Sie dasselbe `partial`-Muster, wenn der Benutzer noch nicht geantwortet hat, der Charakter aber weiter sprechen soll. Fügen Sie eine abschließende Assistant-Nachricht mit dem Charakterpräfix hinzu. ```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 ### Anfrageparameter Gleiches Protokoll wie Qwen Plus Character, mit diesen Unterschieden: | Parameter | Qwen Flash Character | |-----------|----------------------| | `model` | Muss `"qwen-flash-character"` sein | ### Beispielanfrage ```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 } ``` ## Antwortformat Die Qwen Character LLM-Modelle geben OpenAI-kompatible Completion-Antworten zurück. Bei `stream: true` wird die Antwort als Server-Sent Events übertragen; bei `stream: false` als einzelnes JSON-Objekt. ## Bewährte Praktiken - Platzieren Sie Persona-Anweisungen auf Anfrageebene in `system`-Nachrichten. - Legen Sie wiederverwendbaren Charakterhintergrund nur dann in `profile` ab, wenn Langzeitgedächtnis aktiviert ist. - Verwenden Sie denselben `x-session`-Wert über zusammengehörige Gespräche hinweg, wenn Langzeitgedächtnis aktiviert ist. Sitzungen, die 365 Tage nicht verwendet werden, können gelöscht werden. - Senden Sie weiterhin aktuelle Gesprächsnachrichten mit, wenn es sinnvoll ist; Langzeitgedächtnis und kurzfristiger Kontext können zusammenarbeiten. - Schreiben Sie bei der Gruppenchat-Simulation Sprechernamen manuell in `content`. Die API leitet Namen nicht aus `profile` ab. - Verwenden Sie `partial: true` nur in der abschließenden Assistant-Nachricht, wenn das Modell ab einem Präfix fortfahren soll. - Nutzen Sie Qwen Flash Character für leichtgewichtiges Rollenspiel und Qwen Plus Character für reichere Dialogqualität.