> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # AI Chat v2 API Integrationsanleitung > AI Dialogue 集成指南 - XHuoAPI Die AI Chat v2 API (`/aichat2/conversations`) ist die nächste Generation der Dialogschnittstelle und stellt eine umfassende Weiterentwicklung der [AI Chat API](https://api.xhuoapi.ai/documents/59fb1199-6694-4afb-a222-3554d7f7d05a) dar. Basierend auf der einfachen und gehosteten Mehrfachdialogführung von v1 erweitert sie folgende Funktionen: * **Multimodale Benutzereingaben**: Direkte Übermittlung von Text + Bildern + Dateiblöcken über das strukturierte `message`-Feld, ohne vorherige indirekte Anhänge über `references`. * **Agent-basierte Werkzeugaufrufe**: Eingebaute Tools für vernetzte Suche, Web-Scraping, Dateilesen usw. sowie die Möglichkeit, MCP-Server mit Benutzerautorisierung (Google Drive, Notion, Slack, GitHub usw.) anzubinden. Das Modell kann in einer einzigen Anfrage mehrstufig eigenständig Werkzeuge aufrufen, um komplexe Aufgaben zu lösen. * **Strukturierte Streaming-Ereignisse**: Über `accept: text/event-stream` oder `application/x-ndjson` erhält man Token-für-Token Events wie `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` usw., was eine differenzierte Darstellung im Frontend erleichtert. * **Unterbrechbar / Wiederaufnehmbar**: Wenn das Modell weitere Informationen vom Nutzer benötigt, sendet es ein `ask_user_question`-Event und pausiert. Beim nächsten Aufruf kann die Antwort über `tool_results` zurückgegeben werden, um fortzufahren. * **Neue CRUD-Operationen**: Über das gleiche Endpoint können mit dem Feld `action` `retrieve` / `retrieve_batch` / `update` / `delete` ausgeführt werden, ohne separate Sitzungsverwaltungs-APIs. * **Kontinuierlich aktualisierte Modellauswahl**: Standardmäßig sind GPT-5.4, Claude Opus 4.7, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K2.5 und weitere zeitgemäße Modelle verfügbar. Die API ist auf Anfrageebene **vollständig rückwärtskompatibel zu v1**: Es genügt, nur `model` + `question` (+ optional `stateful` / `id` / `references` / `preset`) zu senden, um eine äquivalente `{answer, id}` JSON-Antwort wie in v1 zu erhalten. Daher ist für die Migration von `/aichat/conversations` keine Neukodierung des Clients erforderlich, lediglich der Pfad ist auf `/aichat2/conversations` zu ändern. > Wenn Sie aktuell `/aichat/conversations` verwenden, bleibt die alte Schnittstelle weiterhin verfügbar, sodass Sie in Ihrem eigenen Tempo migrieren können. ## Antragsprozess Um die API zu nutzen, müssen Sie zunächst auf der entsprechenden Seite der [AI Chat v2 API](https://api.xhuoapi.ai/documents/e4a7c2b9-3f1d-4e8a-9b6c-a5d2f8e1b4c7) den Dienst beantragen. Nach dem Aufruf der Seite klicken Sie auf die Schaltfläche „Acquire“, um die für die Anfrage benötigten Zugangsdaten zu erhalten. Sollten Sie noch nicht angemeldet oder registriert sein, werden Sie automatisch zur Anmeldeseite weitergeleitet. Nach Registrierung und Anmeldung kehren Sie automatisch zur ursprünglichen Seite zurück. Beim ersten Antrag erhalten Sie ein kostenloses Kontingent, mit dem Sie die API kostenfrei nutzen können. ## Grundlegende Nutzung Die einfachste Verwendung ist identisch zu v1: Senden Sie `model` + `question` und erhalten Sie `{answer, id}`. CURL-Beispiel: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "question": "用一句话介绍下 XHuoAPI。" }' ``` Antwort: ```json theme={null} { "answer": "XHuoAPI ist eine einheitliche API-Plattform, die führende KI-Modelle und multimodale Dienste aggregiert. Entwickler können mit einem einzigen Schlüssel Dienste wie GPT, Claude, Gemini, Midjourney, Suno, Veo und weitere nutzen.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Python-Beispiel: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/aichat2/conversations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "model": "gpt-5.4", "question": "用一句话介绍下 XHuoAPI。", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` Verfügbare `model`-Werte sind im rechten Try-Panel Dropdown direkt einsehbar. Häufig genutzte Kategorien umfassen: * OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini` usw. * Anthropic: `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` usw. * Google: `gemini-3.1-pro`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-image-preview`, `gemini-3-pro-preview`, `gemini-2.5-flash-lite` usw. * xAI: `grok-4`, `grok-4-1-fast`, `grok-4-1-fast-reasoning`, `grok-3-mini-fast` usw. * DeepSeek: `deepseek-v4-flash`, `deepseek-v3.2-exp`, `deepseek-r1-0528` usw. * Moonshot: `kimi-k2.5`, `kimi-k2-thinking`, `kimi-k2-thinking-turbo` usw. * Zhipu: `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` usw. Details zu den Abrechnungsregeln finden Sie auf der Pricing-Karte der Diensteseite. ## Mehrstufige Dialoge Wie in v1 kann durch Setzen von `stateful: true` die Sitzung gespeichert werden. Die API gibt eine `id` zurück; bei folgenden Anfragen wird diese `id` mitgesendet, um den Dialog fortzusetzen, ohne dass der Client die Nachrichtenhistorie verwalten muss. Erste Anfrage: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "question": "记住一个数字：42。" }' ``` Antwort: ```json theme={null} { "answer": "Okay, ich habe die 42 gespeichert. Was soll ich damit machen?", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Zweite Anfrage mit derselben `id`: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "question": "我刚才让你记住的数字是多少？" }' ``` Antwort: ```json theme={null} { "answer": "Die Zahl, die du mich gebeten hast zu merken, ist 42.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` > `stateful` ist standardmäßig `true`. Das Weglassen entspricht einer expliziten Übergabe von `true`. Wenn Sie nicht möchten, dass der Server den Dialog speichert, setzen Sie `stateful: false`. ## Streaming-Antworten v2 unterstützt zwei Streaming-Formate, die über den `accept`-Header gewählt werden: | Szenario | `accept` | Datenformat | | :------------------------------------ | :---------------------------- | :-------------------------------------------------- | | Web-Frontend / EventSource | `text/event-stream` | `data: {json}\n\n`, letzte Zeile `data: [DONE]\n\n` | | Server / CLI / Node Streaming Parsing | `application/x-ndjson` | Jede Zeile ein JSON-Objekt | | Kein Streaming benötigt | `application/json` (Standard) | Einmalige Rückgabe von `{answer, id}` | ### NDJSON-Beispiel ```python theme={null} import json import requests url = "https://api.xhuoapi.ai/v1/aichat2/conversations" headers = { "accept": "application/x-ndjson", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "model": "gpt-5.4", "stateful": True, "question": "用三句话介绍杭州。", } with requests.post(url, json=payload, headers=headers, stream=True) as resp: answer = "" for line in resp.iter_lines(): if not line: continue event = json.loads(line) if event.get("type") == "text_delta": # Kompatibel zu v1: inkrementelle Fragmente werden auch über delta_answer bereitgestellt answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": print() print("usage =", event.get("usage")) ``` Jede Zeile im NDJSON ist ein strukturiertes Event, am häufigsten `text_delta`: ```json theme={null} {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} {"type":"text_delta","content":"州","delta_answer":"州","id":"f2f4b3e8-..."} {"type":"text_delta","content":"是","delta_answer":"是","id":"f2f4b3e8-..."} ... {"type":"done","conversation_id":"f2f4b3e8-...","usage":{"prompt_tokens":21,"completion_tokens":58,"total_tokens":79},"terminal_reason":"natural_stop"} ``` ### SSE-Beispiel Browserseitig unterstützt `EventSource` keine benutzerdefinierten Request-Bodies. Es wird empfohlen, `fetch` mit manueller Aufteilung nach `\n\n` zu verwenden: ```javascript theme={null} const resp = await fetch("https://api.xhuoapi.ai/v1/aichat2/conversations", { method: "POST", headers: { accept: "text/event-stream", authorization: "Bearer {token}", "content-type": "application/json", }, body: JSON.stringify({ model: "gpt-5.4", stateful: true, question: "用三句话介绍杭州。", }), }); const reader = resp.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; while (true) { const { value, done } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const blocks = buffer.split("\n\n"); buffer = blocks.pop() ?? ""; for (const block of blocks) { const dataLine = block.split("\n").find((l) => l.startsWith("data: ")); if (!dataLine) continue; const payload = dataLine.slice(6); if (payload === "[DONE]") return; const event = JSON.parse(payload); if (event.type === "text_delta") process.stdout.write(event.content); } } ``` ### Streaming-Eventtypen | `type` | Bedeutung | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `text_delta` | Inkrementelle Textfragmente der Antwort. `content` enthält den neuen Inhalt; zur v1-Kompatibilität enthält das Event auch `delta_answer` (gleich `content`) und `id`. | | `thinking` | Denkprozess des Modells (erscheint nur bei Modellen mit aktiviertem Reasoning). | | `tool_use` | Das Modell entscheidet, ein Tool aufzurufen; Event enthält `tool_id`, `tool_name`, `input`. | | `tool_result` | Ergebnis des Toolaufrufs, zugeordnet über `tool_id` zum vorherigen `tool_use`. `is_error` zeigt Fehlerstatus an. | | `card` | Strukturierte Karten, z.B. Bilder oder Linkvorschauen, geeignet zur direkten Darstellung. | | `citation` | Quellen-URL zur Ergänzung von Textabschnitten. | | `ask_user_question` | Das Modell bittet um weitere Nutzerinformationen, Dialog pausiert im Status `awaiting_user_input` (siehe Abschnitt [Dialogwiederaufnahme](#wiederaufnahme-eines-pausierten-dialogs)). | | `artifact` | Vom Modell generierte eigenständige Artefakte (z.B. Codeblöcke, Dokumente), speicher- oder downloadbar. | | `system_message` | Systemhinweise (nicht Nutzer- oder Assistenteninhalt), nur für UI-Anzeigen. | | `compact` | Intern komprimierte Kontext-Events, keine spezielle Behandlung nötig. | | `error` | Fehler in der aktuellen Runde, `message` beschreibt den Fehler. | | `done` | Streaming-Antwort beendet, enthält `usage` (mit `prompt_tokens` / `completion_tokens` / `total_tokens`) und `terminal_reason`. | Clients, die nur an der finalen Antwort interessiert sind, können alle `text_delta`-`content`-Felder zusammenfügen, was dem `answer` im `application/json`-Modus entspricht. ## Multimodale Eingaben Wenn Benutzereingaben Bilder oder Dateien enthalten, senden Sie `message` (Array) anstelle von `question`. Jedes Element ist ein Inhaltsblock: ```json theme={null} { "model": "gpt-5.4", "stateful": true, "message": [ { "type": "text", "text": "这张图片里有几只猫？" }, { "type": "image_url", "image_url": { "url": "https://cdn.xhuoapi.ai/cats.jpg" } } ] } ``` Unterstützte Blocktypen: * `text` — normaler Text, erforderliches Feld `text`. * `image_url` — Bild, erforderliches Feld `image_url.url`. * `file_url` — Datei (PDF, CSV, TXT usw.), erforderliches Feld `file_url.url`. ### Beziehung zu v1 `references` Zur Kompatibilität mit alten Clients erkennt v2 weiterhin das Feld `references: ["https://...", ...]`: * URLs mit Endungen `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif` werden automatisch in `image_url`-Blöcke umgewandelt; * andere Erweiterungen werden in `file_url`-Blöcke umgewandelt; * falls zusätzlich ein `question` übergeben wird, wird diese als `text`-Block vorangestellt. Wenn Sie also nur von v1 migrieren möchten, ohne den Request-Body zu ändern, genügt es, den Pfad auf `/aichat2/conversations` zu ändern. Die bisherige Verwendung von `references` funktioniert weiterhin. Für feinere Steuerung (z.B. mehrere Bilder zwischen Texten oder wichtige Reihenfolge) verwenden Sie direkt das `message`-Array. ## Werkzeugaufrufe und MCP Das Kernfeature von v2 ist, dass das Modell eigenständig Werkzeuge für mehrstufige Aufgaben aufrufen kann. **Dies ist standardmäßig aktiviert** und erfordert keine zusätzliche Konfiguration im Request. Typische Szenarien: * Nutzer fragt: „Suche bitte nach aktuellen Ausstellungen in Shanghai“ → Modell ruft integrierte Websuche auf → Ergebnisse werden in Antwort verarbeitet. * Nutzer fragt: „Lies dieses PDF und schreibe eine Zusammenfassung“ → Modell ruft `file_read` auf → schreibt Zusammenfassung. * Nutzer hat in [Connections](https://api.xhuoapi.ai/connections) Google Drive / GitHub / Notion usw. autorisiert → Modell kann entsprechende MCP-Tools zum Lesen und Schreiben der Daten verwenden. In NDJSON / SSE-Streams werden Werkzeugaufrufe durch `tool_use` und `tool_result` Events dargestellt, z.B.: ```json theme={null} {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} {"type":"tool_result","tool_id":"toolu_01ABCDEF","output":"...","is_error":false,"id":"f2f4b3e8-..."} {"type":"text_delta","content":"目前","delta_answer":"目前","id":"f2f4b3e8-..."} {"type":"text_delta","content":"上海","delta_answer":"上海","id":"f2f4b3e8-..."} ... ``` Wenn Sie die Details der Werkzeugaufrufe im Frontend nicht anzeigen möchten, ignorieren Sie einfach Events der Typen `tool_use` / `tool_result` / `card` / `citation`. Die finale Ausgabe des Modells erfolgt weiterhin über `text_delta`. Mit `max_turns` können Sie die maximale Anzahl der Werkzeugaufrufe pro Anfrage begrenzen. Die Standardobergrenze wird von der Plattform bestimmt. Ein kleiner Wert (z.B. `max_turns: 1`) erzwingt eine Einzelantwort ohne Werkzeugaufrufe. ## Wiederaufnahme eines pausierten Dialogs Einige Werkzeuge lassen das Modell den Nutzer „nachfragen“. Dann sendet das Modell ein `ask_user_question`-Event und der Dialog pausiert im Status `awaiting_user_input`: ```json theme={null} { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", "question": "你希望生成的报告是中文还是英文？", "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` Im Frontend wird dieses Event als Karte dargestellt, damit der Nutzer eine Antwort auswählen kann. Anschließend wird mit derselben `id` eine neue Anfrage gesendet, wobei die Antwort über `tool_results` zurückgegeben wird: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: text/event-stream' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "tool_results": [ { "tool_use_id": "toolu_01XYZW", "output": "中文" } ] }' ``` Das Feld `tool_use_id` im Request-Body **muss** exakt mit dem `tool_id` des pausierten Events übereinstimmen; andernfalls wird ein 400-Fehler zurückgegeben. Wenn `tool_results` übermittelt werden, werden `question` / `message` / `references` ignoriert. Wenn der Nutzer die Frage überspringen möchte, kann er einfach eine neue `question` oder `message` senden; die Plattform markiert den pausierten Werkzeugaufruf automatisch als „vom Nutzer übersprungen“. ## Sitzungsverwaltung (CRUD) v2 bietet über das gleiche Endpoint mit dem Feld `action` eine leichte Sitzungsverwaltung, ohne separate API öffnen zu müssen. ### `action: retrieve` — Eine Sitzung abrufen ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "retrieve", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" }' ``` Gibt das vollständige Sitzungsdokument zurück (inklusive `messages`-Historie, `model`, `title`, `tools_used` usw.). ### `action: retrieve_batch` — Sitzungsübersichten auflisten ```json theme={null} { "action": "retrieve_batch", "model_group": "chatgpt", "limit": 20, "offset": 0 } ``` Gibt `{ items: [...], total }` zurück. **Die Übersicht enthält keine `messages`**, eignet sich für Seitenleistenlisten. Wenn ein Nutzer eine Sitzung öffnet, kann mit `action: retrieve` die vollständige Nachrichtengeschichte geladen werden. Optionale Filterparameter: `user_id`, `application_id`, `model_group`, `model`. ### `action: update` — Titel ändern oder Verlauf neu schreiben ```json theme={null} { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "title": "Reiseplan für Hangzhou" } ``` `messages` können ebenfalls übergeben werden, jedoch führt der Server eine strenge Schema-Prüfung durch (muss die gefaltete `ToolUseContent`-Form haben), andernfalls wird ein 400-Fehler zurückgegeben. In der Regel wird dies nur zum Ändern des `title` empfohlen. ### `action: delete` — Eine Sitzung löschen ```json theme={null} { "action": "delete", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Gibt `{ id, success: true }` zurück. Gelöschte Sitzungen können nicht wiederhergestellt werden. Bitte bestätigen Sie vor dem Aufruf. ## Sanfte Migration von v1 Wenn Sie bereits [`/aichat/conversations`](https://api.xhuoapi.ai/documents/59fb1199-6694-4afb-a222-3554d7f7d05a) nutzen, ist die Migration zu v2 nahezu ohne Codeänderungen möglich: 1. Ändern Sie die URL von `https://api.xhuoapi.ai/v1/aichat/conversations` zu `https://api.xhuoapi.ai/v1/aichat2/conversations`. 2. Wenn Sie bisher v1-Modellnamen (z.B. `gpt-3.5`, `gpt-4-browsing` usw.) verwendet haben, empfehlen wir bei v2 ein Upgrade auf zeitgemäße Modelle (z.B. `gpt-5.4`, `claude-opus-4-7`, `gemini-3.1-pro` usw.). 3. Die NDJSON-Stream-Felder bleiben rückwärtskompatibel: Jedes `text_delta`-Event enthält weiterhin `delta_answer` und `id`, sodass Clients, die `delta_answer` zeilenweise parsen, keine Änderungen benötigen. Nach der Migration können Sie die neuen v2-Funktionen (multimodale `message`, SSE, Werkzeugaufrufe, `action` CRUD) nach Bedarf aktivieren und schrittweise einführen. ## Fehlerbehandlung Fehlerantworten haben ein einheitliches Format: ```json theme={null} { "error": { "code": "chat_error", "message": "upstream LLM returned an error" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` Häufige Fehler: * `400 bad_request`: Fehlende Pflichtfelder, nicht übereinstimmende `tool_use_id`, ungültiges `messages`-Schema usw. * `401 invalid_token`: Ungültiger `authorization`-Header. * `404 not_found`: Bei `action: retrieve / update / delete` existiert die angegebene Sitzung nicht. * `429 too_many_requests`: Rate-Limiting wurde ausgelöst. * `500 chat_error`: Fehler im Upstream-LLM oder `completion_tokens=0` in der Runde (wird als nicht verbraucht behandelt, keine Kosten). In Streaming-Antworten werden Fehler als `{"type":"error","message":"..."}`-Event gesendet, danach endet der Stream. ## Fazit Die AI Chat v2 API ist rückwärtskompatibel zu v1 und erweitert den Dialog von „Einzel- / Mehrfachfragen“ zu einem „Agent-basierten, beobachtbaren Dialog“: multimodale Eingaben, Werkzeugaufrufe, pausierbar / wiederaufnehmbar, strukturierte Streaming-Events, integriertes CRUD. Wir empfehlen für Neuanbindungen direkt v2 zu verwenden; bestehende v1-Integrationen können schrittweise migriert werden. Bei Fragen steht unser technischer Support jederzeit zur Verfügung.