AI Chat v2 API Integrationsanleitung

Die AI Chat v2 API (/aichat2/conversations) ist die nächste Generation der Dialogschnittstelle und stellt eine umfassende Weiterentwicklung der AI Chat API 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 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:

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:

{
  "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:

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:

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:

{
  "answer": "Okay, ich habe die 42 gespeichert. Was soll ich damit machen?",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

Zweite Anfrage mit derselben id:

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:

{
  "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

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:

{"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:

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).
`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:

{
  "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 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.:

{"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:

{
  "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:

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

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

{
  "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

{
  "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

{
  "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 nutzen, ist die Migration zu v2 nahezu ohne Codeänderungen möglich:

Ändern Sie die URL von https://api.xhuoapi.ai/v1/aichat/conversations zu https://api.xhuoapi.ai/v1/aichat2/conversations.
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.).
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:

{
  "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.

Documentation Index

​Antragsprozess

​Grundlegende Nutzung

​Mehrstufige Dialoge

​Streaming-Antworten

​NDJSON-Beispiel

​SSE-Beispiel

​Streaming-Eventtypen

​Multimodale Eingaben

​Beziehung zu v1 references

​Werkzeugaufrufe und MCP

​Wiederaufnahme eines pausierten Dialogs

​Sitzungsverwaltung (CRUD)

​action: retrieve — Eine Sitzung abrufen

​action: retrieve_batch — Sitzungsübersichten auflisten

​action: update — Titel ändern oder Verlauf neu schreiben

​action: delete — Eine Sitzung löschen

​Sanfte Migration von v1

​Fehlerbehandlung

​Fazit

Antragsprozess

Grundlegende Nutzung

Mehrstufige Dialoge

Streaming-Antworten

NDJSON-Beispiel

SSE-Beispiel

Streaming-Eventtypen

Multimodale Eingaben

Beziehung zu v1 `references`

Werkzeugaufrufe und MCP

Wiederaufnahme eines pausierten Dialogs

Sitzungsverwaltung (CRUD)

`action: retrieve` — Eine Sitzung abrufen

`action: retrieve_batch` — Sitzungsübersichten auflisten

`action: update` — Titel ändern oder Verlauf neu schreiben

`action: delete` — Eine Sitzung löschen

Sanfte Migration von v1

Fehlerbehandlung

Fazit