> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # AI Chat v2 API Integrationsanleitung > AI Dialogue API guide - Ace Data Cloud Die AI Chat v2 API (`/aichat2/conversations`) ist die nächste Generation der Dialogschnittstelle und eine umfassende Upgrade-Version der [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Sie erweitert die v1, die einfach und für mehrstufige Dialoge gehostet ist, um: * **Multimodale Benutzereingaben**: Direkte Übertragung von Text + Bildern + Dateiblöcken über das strukturierte `message`-Feld, ohne vorherige indirekte Anhänge über `references`. * **Agentenbasierte Werkzeugaufrufe**: Eingebaute Tools für Online-Suche, Web-Scraping, Dateilesen usw., die mit vom Benutzer autorisierten MCP-Servern (Google Drive, Notion, Slack, GitHub usw.) verbunden werden können, sodass das Modell in einer Anfrage mehrere Werkzeuge selbstständig aufrufen kann, um komplexe Aufgaben zu erledigen. * **Strukturierte Streaming-Ereignisse**: Durch `accept: text/event-stream` oder `application/x-ndjson` können Ereignisse wie `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` usw. tokenweise abgerufen werden, was die separate Darstellung im Frontend nach Typ erleichtert. * **Unterbrechbar / Wiederherstellbar**: Das Modell sendet ein `ask_user_question`-Ereignis und pausiert, wenn es zusätzliche Informationen vom Benutzer benötigt; beim nächsten Aufruf kann die Antwort über `tool_results` zurückgegeben werden, um fortzufahren. * **Neue CRUD-Aktionen**: Über das gleiche Endpoint können durch das `action`-Feld `retrieve` / `retrieve_batch` / `update` / `delete` durchgeführt werden, ohne zusätzliche Sitzungsverwaltungs-APIs. * **Aktualisierte Modellliste**: Standardmäßig sind GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 und andere zeitgenössische Modelle integriert. Gleichzeitig ist die API auf der Anfrageebene **vollständig rückwärtskompatibel mit v1**: Es genügt, `model` + `question` (plus optional `stateful` / `id` / `references` / `preset`) zu übermitteln, um die äquivalente `{answer, id}` JSON-Antwort wie in v1 zu erhalten, sodass eine Migration von `/aichat/conversations` nicht erfordert, dass der Client neu geschrieben wird; es genügt, den Pfad auf `/aichat2/conversations` zu ändern. > Wenn Sie derzeit `/aichat/conversations` verwenden, bleibt die alte Schnittstelle weiterhin verfügbar, sodass Sie in Ihrem eigenen Tempo migrieren können. ## Antragsprozess Um die AI Chat v2 API zu nutzen, gehen Sie zunächst zur [Ace Data Cloud Konsole](https://platform.acedata.cloud/console/applications), um Ihr API-Token zu erhalten, das Sie zur Sicherheit aufbewahren sollten. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, wo Sie sich registrieren und anmelden können. Nach Abschluss werden Sie automatisch zur aktuellen Seite zurückgeleitet. **Ein API-Token reicht aus, um auf alle Dienste der Plattform zuzugreifen, ohne dass für jeden Dienst separat beantragt werden muss.** Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um es kostenlos auszuprobieren; wenn das Kontingent erschöpft ist, können Sie im [Dashboard](https://platform.acedata.cloud/console/coin) Ihr allgemeines Guthaben aufladen. > 📘 Vollständige Dokumentation: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Grundlegende Nutzung Die einfachste Verwendung ist identisch mit v1: Übertragen Sie `model` + `question`, um `{answer, id}` zu erhalten. CURL-Beispiel: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "question": "Stellen Sie AceDataCloud in einem Satz vor." }' ``` Rückgabe: ```json theme={null} { "answer": "AceDataCloud ist eine einheitliche API-Plattform, die führende AI-Modelle und multimodale Dienste aggregiert, sodass Entwickler mit einem Schlüssel auf Dienste wie GPT, Claude, Gemini, Midjourney, Suno, Veo usw. zugreifen können.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Python-Beispiel: ```python theme={null} import requests url = "https://api.acedata.cloud/aichat2/conversations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "model": "gpt-5.4", "question": "Stellen Sie AceDataCloud in einem Satz vor.", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` Verfügbare `model`-Werte können im Dropdown-Menü im rechten Try-Bereich direkt angezeigt werden, gängige 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-8`, `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` usw. * DeepSeek: `deepseek-v4-flash`, `deepseek-v3.2-exp`, `deepseek-r1-0528` usw. * Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` usw. * Zhipu: `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` usw. Die spezifischen Abrechnungsregeln finden Sie auf der Preisseite des Dienstes. ## Mehrstufige Dialoge Wie in v1 können Sie `stateful: true` übermitteln, um die Sitzungsspeicherung zu aktivieren; die API gibt eine `id` zurück. Bei nachfolgenden Anfragen bringen Sie einfach die `id` mit, um das Gespräch fortzusetzen, ohne die Nachrichtenhistorie selbst verwalten zu müssen. Erste Anfrage: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", "stateful": true, "question": "Merken Sie sich eine Zahl: 42." }' ``` Rückgabe: ```json theme={null} { "answer": "Okay, ich habe 42 gespeichert. Was soll ich damit machen?", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Zweite Anfrage, mit der gleichen `id`: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/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": "Was war die Zahl, die ich dich gerade gebeten habe, dir zu merken?" }' ``` ```json theme={null} { "answer": "Die Zahl, die du mich hast merken lassen, ist 42.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` > `stateful` ist standardmäßig `true`, das Weglassen und das explizite Übertragen von `true` sind gleichwertig. Wenn du nicht möchtest, dass der Server diese Runde des Gesprächs speichert, kannst du `stateful: false` explizit festlegen. ## Stream-Antwort v2 unterstützt zwei Arten von Streaming-Formaten, je nach `accept`-Header: | Szenario | `accept` | Datenform | | ------------------------------------- | ----------------------------- | --------------------------------------------------- | | Web-Frontend / EventSource | `text/event-stream` | `data: {json}\n\n`, letzte Zeile `data: [DONE]\n\n` | | Server / CLI / Node Streaming-Parsing | `application/x-ndjson` | Ein JSON-Objekt pro Zeile | | Kein Streaming | `application/json` (Standard) | Einmalige Rückgabe `{answer, id}` | ### NDJSON Beispiel ```python theme={null} import json import requests url = "https://api.acedata.cloud/aichat2/conversations" headers = { "accept": "application/x-ndjson", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "model": "gpt-5.4", "stateful": True, "question": "Stelle Hangzhou in drei Sätzen vor.", } 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 mit v1: Inkrementelle Fragmente werden auch über das delta_answer-Feld bereitgestellt answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": print() print("usage =", event.get("usage")) ``` NDJSON jede Zeile ist ein strukturiertes Ereignis, am häufigsten ist `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 Im Browser verwendet `EventSource` keine benutzerdefinierten Anforderungskörper, es wird empfohlen, `fetch` + manuelles Zerlegen nach `\n\n` zu verwenden: ```javascript theme={null} const resp = await fetch("https://api.acedata.cloud/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: "Stelle Hangzhou in drei Sätzen vor.", }), }); 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-Ereignistypen | `type` | Bedeutung | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text_delta` | Inkrementelle Textfragmente der Antwort des Assistenten. `content` ist der neue Inhalt; zur Kompatibilität mit v1 enthält dasselbe Ereignis auch `delta_answer` (gleich `content`) und `id`. | | `thinking` | Der Denkprozess des Modells (erscheint nur, wenn das gewählte Modell Reasoning offenlegt). | | `tool_use` | Das Modell entscheidet sich, ein Werkzeug zu verwenden, das Ereignis enthält `tool_id`, `tool_name`, `input`. | | `tool_result` | Ergebnis der Werkzeugausführung, gepaart mit der vorherigen `tool_use` über `tool_id`, `is_error` kennzeichnet, ob es fehlgeschlagen ist. | | `card` | Strukturierte Karten, die von Werkzeugen erzeugt werden (z. B. Bilder, Linkvorschauen), geeignet für die direkte Darstellung. | | `citation` | Dient zur Ergänzung der Quelle URL des entsprechenden Textabschnitts. | | `ask_user_question` | Das Modell sendet eine Anfrage an den Benutzer, um zusätzliche Informationen bereitzustellen, das Gespräch wechselt in den Status `awaiting_user_input`, siehe unten [Wiederherstellung eines pausierten Gesprächs](#wiederherstellung-eines-pausierten-gesprächs). | | `artifact` | Unabhängige Produkte, die vom Modell erzeugt werden (z. B. Codeblöcke, Dokumente), die gespeichert oder heruntergeladen werden können. | | `system_message` | Systembenachrichtigungen (nicht Benutzer- und Assistenteninhalt), nur für UI-Hinweise verwendet. | | `compact` | Ereignisse, bei denen der interne Kontext komprimiert wurde, benötigen keine spezielle Behandlung. | | `error` | Ein Fehler ist in dieser Runde aufgetreten, `message` beschreibt den Fehlerinhalt. | | `done` | Ende der Streaming-Antwort, enthält `usage` (einschließlich `prompt_tokens` / `completion_tokens` / `total_tokens`) und `terminal_reason`. | Für Clients, die nur an der endgültigen Antwort interessiert sind, ist das Zusammenfügen aller `text_delta`-Inhalte gleichwertig mit der `answer` im `application/json`-Modus. ## Multimodale Eingaben Wenn die Benutzereingabe Bilder oder Dateien enthält, übertrage `message` (Array) anstelle von `question`. Jedes Element des Arrays ist ein Inhaltsblock: ```json theme={null} { "model": "gpt-5.4", "stateful": true, "message": [ { "type": "text", "text": "Wie viele Katzen sind auf diesem Bild?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } } ] } ``` Unterstützte Blocktypen: * `text` — Normaler Text, das Feld `text` ist erforderlich. * `image_url` — Bild, das Feld `image_url.url` ist erforderlich. * `file_url` — Datei (PDF, CSV, TXT usw.), das Feld `file_url.url` ist erforderlich. ### Beziehung zu v1 `references` Um die Kompatibilität mit alten Clients zu gewährleisten, erkennt v2 weiterhin das Feld `references: ["https://...", ...]`: * URL-Endungen sind `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automatisch in einen `image_url` Block umgewandelt; * Andere Dateiendungen werden in einen `file_url` Block umgewandelt; * Wenn gleichzeitig eine `question` bereitgestellt wird, wird sie als ein `text` Block vorangestellt. Wenn Sie also nur von v1 migrieren möchten, ohne den Anfragekörper zu ändern, ändern Sie einfach den Pfad in `/aichat2/conversations`, die ursprüngliche Verwendung von `references` funktioniert wie gewohnt. Für eine genauere Kontrolle (zum Beispiel mehrere Bilder zwischen Texten zu platzieren oder wenn die Reihenfolge wichtig ist) verwenden Sie einfach das `message` Array. ## Werkzeugaufrufe und MCP Der Kernpunkt der v2 Verbesserung ist, dass das Modell Werkzeuge selbstständig aufrufen kann, um mehrstufige Aufgaben zu erledigen, **dies ist standardmäßig aktiviert**, und der Client muss keine zusätzlichen Konfigurationen in der Anfrage vornehmen. Häufige Szenarien: * Der Benutzer fragt: „Hilf mir, die neuesten Ausstellungen in Shanghai zu finden“ → Modell ruft die integrierte Websuche auf → organisiert die Ergebnisse in einer Antwort. * Der Benutzer fragt: „Lies dieses PDF und schreibe eine Zusammenfassung“ → Modell ruft file\_read auf → schreibt die Zusammenfassung. * Der Benutzer hat in [Connections](https://platform.acedata.cloud/connections) Google Drive / GitHub / Notion usw. autorisiert → Modell kann die entsprechenden MCP-Werkzeuge aufrufen, um Daten zu lesen und zu schreiben. In NDJSON / SSE-Streams werden Werkzeugaufrufe durch die Ereignisse `tool_use` und `tool_result` dargestellt, zum Beispiel: ```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 nicht im Frontend anzeigen möchten, ignorieren Sie einfach die Ereignisse `tool_use` / `tool_result` / `card` / `citation`, die endgültige Ausgabe des Modells erfolgt weiterhin über `text_delta`. `max_turns` kann die maximale Anzahl der Selbstaufrufe des Modells in dieser Anfrage begrenzen, das Standardlimit wird von der Plattform festgelegt. Wenn Sie es klein setzen (zum Beispiel `max_turns: 1`), können Sie eine einmalige Antwort erzwingen und keine Werkzeugaufrufe zulassen. ## Asynchrone Ausführung und unbeaufsichtigte Autorisierung Wenn Ihr Aufruf von einem Alarm-Webhook, CI/CD, Überwachungssystem oder anderen Hintergrundaufgaben stammt, können Sie `async: true` setzen, um die Schnittstelle sofort die Aufgaben-ID zurückzugeben, während im Hintergrund weiter ausgeführt wird: ```json theme={null} { "model": "gpt-5.5", "async": true, "question": "Mein Dienst hat Alarm geschlagen, benutze WeChat, um die WeChat-Gruppe „AceDataCloud-Team“ zu benachrichtigen……" } ``` Beispielantwort: ```json theme={null} { "task_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "conversation_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "status": "queued" } ``` Danach können Sie `action: retrieve` + `id` verwenden, um die Sitzungsergebnisse abzufragen; Sie können auch `callback_url` bereitstellen, die Plattform wird `{ status, answer, usage, error }` nach Abschluss der Aufgabe an Ihre Rückrufadresse POSTen. `callback_url` muss `http` / `https` verwenden und darf keine direkte Eingabe von `localhost` oder privaten IP-Adressen sein. Hintergrundaufgaben können normalerweise nicht von jemandem bestätigt werden. Wenn Sie möchten, dass bestimmte Skills oder MCP-Server im unbeaufsichtigten Modus Aktionen wie Senden, Veröffentlichen, Schreiben usw. ausführen, geben Sie in der Anfrage explizit die Liste der vorab autorisierten Elemente an: ```json theme={null} { "model": "gpt-5.5", "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "question": "Mein Dienst hat Alarm geschlagen, benutze WeChat, um die WeChat-Gruppe „AceDataCloud-Team“ zu benachrichtigen……" } ``` Die Werte in `allowed_skills` sind die Slugs der verbundenen Skills; die Werte in `allowed_mcp_servers` sind die Slugs der verbundenen MCP-Server. Skills / MCP-Server, die nicht in der vorab autorisierten Liste aufgeführt sind, können im unbeaufsichtigten Modus weiterhin nur Vorschau-, Dry-Run- oder Schreiboperationen ablehnen. Wenn Sie eine genauere Kontrolle benötigen, können Sie auch das äquivalente `unattended_policy` Objekt verwenden: ```json theme={null} { "unattended_policy": { "mode": "allow_selected", "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "expires_at": 1790000000 } } ``` Hinweis: Die Vorabautorisierung bedeutet nur, dass „diese Fähigkeiten in dieser Anfrage im unbeaufsichtigten Modus ohne menschliche Bestätigung übersprungen werden dürfen“. Bestimmte Skills müssen weiterhin `--unattended-confirm` oder entsprechende Sicherheitsmechanismen unterstützen; andernfalls wird weiterhin ein Dry-Run durchgeführt und keine Schreiboperationen direkt ausgeführt. ## Wiederherstellung pausierter Gespräche Einige Werkzeuge lassen das Modell „den Benutzer fragen“, das Modell sendet dann ein `ask_user_question` Ereignis, das Gespräch wird im Status `awaiting_user_input` eingefroren: ```json theme={null} { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", "question": "Möchten Sie, dass der Bericht auf Chinesisch oder Englisch erstellt wird?", "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` Im Frontend wird dieses Ereignis als Karte gerendert, damit der Benutzer eine Antwort auswählen kann, und dann wird mit derselben `id` die nächste Anfrage gestartet, wobei die Antwort über `tool_results` zurückgegeben wird: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/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": "中文" } ] }' ``` Im Anfragekörper muss `tool_use_id` **genau** mit der `tool_id` zum Zeitpunkt der Pause übereinstimmen; eine Abweichung führt zu einem 400-Fehler. Wenn in der Anfrage gleichzeitig `tool_results` vorhanden sind, werden `question` / `message` / `references` ignoriert. Wenn der Benutzer beschließt, diese Frage aufzugeben, senden Sie einfach eine neue `question` / `message`, die Plattform wird den pausierten Werkzeugaufruf automatisch als „Benutzer übersprungen“ markieren. ## Sitzungsmanagement (CRUD) v2 bietet leichtgewichtiges Sitzungsmanagement über das `action` Feld am selben Endpunkt, ohne dass eine zusätzliche API erforderlich ist. ### `action: retrieve` —— Eine Sitzung abrufen ```shell theme={null} curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "retrieve", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" }' ``` Geben Sie das vollständige Sitzungsdokument zurück (einschließlich `messages` Verlauf, `model`, `title`, `tools_used` usw.). ### `action: retrieve_batch` —— Sitzungszusammenfassungen auflisten ```json theme={null} { "action": "retrieve_batch", "model_group": "chatgpt", "limit": 20, "offset": 0 } ``` Geben Sie `{ items: [...], total }` zurück. **Die Zusammenfassung enthält keine `messages`**, geeignet für eine Seitenleistenliste; wenn der Benutzer eine Sitzung öffnet, verwenden Sie `action: retrieve`, um die vollständigen Nachrichten separat abzurufen. 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 Hangzhou" } ``` `messages` können ebenfalls übergeben werden, aber der Server führt eine strenge Schemaüberprüfung durch (muss in der gefalteten `ToolUseContent`-Form vorliegen), andernfalls wird 400 zurückgegeben. Allgemein wird empfohlen, nur den `title` zu ändern. ### `action: delete` —— Eine Sitzung löschen ```json theme={null} { "action": "delete", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Geben Sie `{ id, success: true }` zurück. Nach dem Löschen kann nicht wiederhergestellt werden, bitte bestätigen Sie dies, bevor Sie den Aufruf tätigen. ## Sanfte Migration von v1 Wenn Sie bereits [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations) verwenden, erfordert die Migration zu v2 fast keine Codeänderungen: 1. Ändern Sie die URL von `https://api.acedata.cloud/aichat/conversations` zu `https://api.acedata.cloud/aichat2/conversations`. 2. Wenn Sie zuvor v1 Modellnamen (wie `gpt-3.5`, `gpt-4-browsing` usw.) übergeben haben, wird empfohlen, beim Wechsel zu v2 auf moderne Modelle (wie `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro` usw.) zu aktualisieren. 3. Die Felder des NDJSON-Streams bleiben rückwärtskompatibel: Jedes `text_delta`-Ereignis enthält weiterhin `delta_answer` und `id`, sodass der ursprüngliche Client, der `delta_answer` zeilenweise analysiert, keine Änderungen vornehmen muss. Nach der Migration können Sie die neuen Funktionen von v2 nach Bedarf aktivieren (multimodale `message`, SSE, Toolaufrufe, `action` CRUD), und dies in Ihrem eigenen Tempo vorantreiben. ## Fehlerbehandlung Fehlerantworten sind einheitlich: ```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 erforderliche Felder, `tool_use_id` stimmt nicht überein, `messages`-Schema ist ungültig usw. * `401 invalid_token`: `authorization`-Header ist nicht korrekt. * `404 not_found`: Bei `action: retrieve / update / delete` existiert die Sitzung mit der entsprechenden `id` nicht. * `429 too_many_requests`: Die Ratebegrenzung wurde ausgelöst. * `500 chat_error`: Der upstream LLM hat einen Fehler zurückgegeben oder in dieser Runde `completion_tokens=0` (wird als nicht verbraucht behandelt, es fallen keine Kosten an). In der Streaming-Antwort werden Fehler als `{"type":"error","message":"..."}`-Ereignis gesendet, gefolgt von einem sofortigen Ende des Streams. ## Fazit Die AI Chat v2 API ist rückwärtskompatibel mit v1 und hat die Konversation von „einzelner / mehrerer Fragen und Antworten“ auf „agentenbasierte beobachtbare Konversation“ aufgerüstet: multimodale Eingaben, Toolaufrufe, pausierbar / wiederherstellbar, strukturierte Ereignisse im Stream, integriertes CRUD. Es wird empfohlen, neue Integrationen direkt v2 zu verwenden; bestehende v1-Integrationen können schrittweise migriert werden. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.