> ## 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 Dialogschnittstelle der neuen Generation und eine umfassend aktualisierte Version der [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Auf Grundlage der einfachen, gehosteten Mehrturn-Dialoge von v1 erweitert sie um:

* **Multimodale Benutzereingaben**: Über das strukturierte Feld `message` können Text-, Bild- und Dateiblöcke direkt übergeben werden, ohne sie zuvor indirekt über `references` anzuhängen.
* **Agent-basierte Tool-Aufrufe**: Eine Reihe integrierter Tools für Websuche, Abrufen von Webseiten, Lesen von Dateien usw. sowie die Möglichkeit, vom Benutzer autorisierte MCP-Server (Google Drive, Notion, Slack, GitHub usw.) einzubinden. Das Modell kann Tools innerhalb einer Anfrage eigenständig über mehrere Runden aufrufen, um komplexe Aufgaben abzuschließen.
* **Strukturierte Streaming-Ereignisse**: Über `accept: text/event-stream` oder `application/x-ndjson` können Ereignisse wie `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card` und `artifact` tokenweise abgerufen werden, damit sie im Frontend je nach Typ separat gerendert werden können.
* **Unterbrechbar / fortsetzbar**: Wenn das Modell zusätzliche Informationen vom Benutzer benötigt, sendet es ein `ask_user_question`-Ereignis und pausiert. Beim nächsten Aufruf kann die Antwort über `tool_results` zurückgegeben werden, um fortzufahren.
* **Neue CRUD-Aktionen**: Über das Feld `action` können auf demselben Endpoint `retrieve` / `retrieve_batch` / `update` / `delete` ausgeführt werden, ohne dass eine zusätzliche API zur Sitzungsverwaltung erforderlich ist.
* **Kontinuierlich aktualisierte Modellliste**: Standardmäßig sind aktuelle Modelle wie GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4 und Kimi K3 integriert.

Gleichzeitig ist sie auf Anfragekörper-Ebene **vollständig abwärtskompatibel mit v1**: Wenn nur `model` + `question` (+ optional `stateful` / `id` / `references` / `preset`) übergeben werden, erhalten Sie eine zu v1 gleichwertige JSON-Antwort `{answer, id}`. Daher muss der Client bei der Migration von `/aichat/conversations` nicht neu geschrieben werden; es genügt, den Pfad zu `/aichat2/conversations` zu ändern.

> Wenn Sie derzeit `/aichat/conversations` verwenden, bleibt die alte Schnittstelle weiterhin verfügbar, und Sie können in Ihrem eigenen Tempo migrieren.

## Antragsprozess

Um die AI Chat v2 API zu verwenden, holen Sie sich zunächst in der [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) Ihren API-Token und bewahren Sie ihn als Reserve auf.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Anschließend kehren Sie automatisch zu dieser Seite zurück.

**Ein API-Token kann alle Dienste der Plattform aufrufen; Sie müssen ihn nicht für jeden Dienst separat beantragen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben, um den Dienst kostenlos zu testen; bei unzureichendem Guthaben können Sie in der [Konsole](https://platform.acedata.cloud/console/coin) allgemeines Guthaben aufladen.

> 📘 Vollständige Dokumentation: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations)

## Grundlegende Verwendung

Die einfachste Verwendung ist vollständig identisch mit v1: Übergeben Sie `model` + `question` und erhalten Sie `{answer, id}`.

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": "用一句话介绍下 AceDataCloud。"
  }'
```

Rückgabeergebnis:

```json theme={null}
{
  "answer": "AceDataCloud 是一个聚合主流 AI 模型与多模态服务的统一 API 平台，开发者通过一个密钥即可调用 GPT、Claude、Gemini、Midjourney、Suno、Veo 等多家服务。",
  "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": "用一句话介绍下 AceDataCloud。",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Die verfügbaren Werte für `model` können direkt im Dropdown-Menü des Try-Bereichs auf der rechten Seite eingesehen werden. Häufig verwendete 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-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-image`, `gemini-3.1-pro-preview`, `gemini-2.5-flash-lite` usw.
* xAI: `grok-4` usw.
* DeepSeek: `deepseek-v4-pro`, `deepseek-v4.1-flash`, `deepseek-v4-flash`, `deepseek-v3.2-exp`, `deepseek-r1-0528` usw.
* Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` usw.
* Zhipu: `glm-5.3`, `glm-5.2`, `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` usw.

Die konkreten Abrechnungsregeln finden Sie auf der Dienstseite in der Pricing-Karte.

## Mehrturn-Dialoge

Wie bei v1 aktiviert die Übergabe von `stateful: true` das Speichern der Sitzung. Die API gibt eine `id` zurück; bei nachfolgenden Anfragen genügt es, diese `id` erneut mitzusenden, um den Dialog fortzusetzen, ohne dass Sie den Nachrichtenverlauf selbst verwalten 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": "记住一个数字：42。"
  }'
```

Rückgabe:

```json theme={null}
{
  "answer": "好的，我已经记住了 42。需要我用它做什么吗？",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}
```

Zweite Anfrage, mit derselben `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": "我刚才让你记住的数字是多少？"
  }'
```

```json theme={null}
{
  "answer": "你让我记住的数字是 42。",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}
```

> `stateful` ist standardmäßig `true`; das Weglassen ist gleichbedeutend mit der expliziten Übergabe von `true`. Wenn du nicht möchtest, dass der Server diese Gesprächsrunde speichert, kannst du explizit `stateful: false` setzen.

## Streaming-Antworten

v2 unterstützt zwei Streaming-Formate, die über den `accept`-Header ausgewählt werden:

| 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 erforderlich | `application/json`（Standard） | Einmalige Rückgabe von `{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": "用三句话介绍杭州。",
}

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":
            # 与 v1 兼容：增量片段同时通过 delta_answer 字段提供
            answer += event["content"]
            print(event["delta_answer"], end="", flush=True)
        elif event.get("type") == "done":
            print()
            print("usage =", event.get("usage"))
```

Jede NDJSON-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

Die Verwendung von `EventSource` im Browser unterstützt keine benutzerdefinierten Request-Bodies; empfohlen wird `fetch` + manuelles Parsen in Scheiben nach `\n\n`:

```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: "用三句话介绍杭州。",
  }),
});

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` | Inkrementelles Textfragment der Assistentenantwort. `content` enthält den neuen Inhalt; zur Kompatibilität mit v1 enthält dasselbe Ereignis auch `delta_answer` (gleich `content`) und `id`. |
| `thinking` | Denkprozess des Modells (tritt nur auf, wenn das ausgewählte Modell Reasoning offenlegt). |
| `tool_use` | Das Modell entscheidet, ein Tool aufzurufen; das Ereignis enthält `tool_id`, `tool_name`, `input`. |
| `tool_result` | Tool-Ausführungsergebnis, über `tool_id` mit dem vorherigen `tool_use` gekoppelt; `is_error` kennzeichnet, ob es fehlgeschlagen ist. |
| `card` | Vom Tool erzeugte strukturierte Karte (z. B. Bild, Link-Vorschau), geeignet zum direkten Rendern. |
| `citation` | Quell-URL zur Ergänzung von Zitaten für das entsprechende Textfragment. |
| `ask_user_question` | Wird ausgegeben, wenn das Modell zusätzliche Informationen vom Benutzer benötigt; das Gespräch wechselt in den Status `awaiting_user_input`, siehe unten [Pausierte Gespräche fortsetzen](#恢复暂停的对话). |
| `artifact` | Eigenständiges vom Modell erzeugtes Ergebnis (z. B. Codeblock, Dokument), das gespeichert oder heruntergeladen werden kann. |
| `system_message` | Systemhinweis (kein Benutzer- oder Assistenteninhalt), nur für UI-Hinweise. |
| `compact` | Ereignis, bei dem der interne Kontext komprimiert wurde; keine besondere Behandlung erforderlich. |
| `error` | In dieser Runde ist ein Fehler aufgetreten; `message` beschreibt den Fehlerinhalt. |
| `done` | Streaming-Antwort beendet; enthält `usage` (einschließlich `prompt_tokens` / `completion_tokens` / `total_tokens`) und `terminal_reason`. |

Für Clients, die sich nur für die endgültige Antwort interessieren, ist das Zusammenfügen aller `content`-Werte von `text_delta` gleichbedeutend mit `answer` im Modus `application/json`.

## Multimodale Eingaben

Wenn die Benutzereingabe Bilder oder Dateien enthält, übergib `message` (ein Array) anstelle von `question`. Jedes Array-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.acedata.cloud/cats.jpg" } }
  ]
}
```

Unterstützte Blocktypen:

* `text` — Normaler Text, das Feld `text` ist erforderlich.
* `image_url` — Bild, `image_url.url` ist erforderlich.
* `file_url` — Datei (PDF, CSV, TXT usw.), `file_url.url` ist erforderlich.

### Beziehung zu v1 `references`

Zur Kompatibilität mit alten Clients erkennt v2 weiterhin das Feld `references: ["https://...", ...]`:

* URL-Suffix ist `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automatisch in einen `image_url`-Block umwandeln;
* Andere Erweiterungen in einen `file_url`-Block umwandeln;
* Wenn gleichzeitig auch `question` bereitgestellt wird, diese als `text`-Block voranstellen.

Wenn du daher nur von v1 migrieren möchtest und den Request-Body nicht ändern willst, ersetze einfach den Pfad durch `/aichat2/conversations`; die ursprüngliche Verwendung von `references` funktioniert weiterhin wie gewohnt.

Wenn eine feinere Steuerung erforderlich ist (zum Beispiel, um mehrere Bilder zwischen Text zu platzieren, oder wenn die Reihenfolge wichtig ist), verwende direkt das `message`-Array.

## Tool-Aufrufe und MCP

Die zentrale Erweiterung von v2 besteht darin, dass das Modell selbstständig Tools aufrufen kann, um mehrstufige Aufgaben zu erledigen. **Dies ist standardmäßig aktiviert**, und der Client muss keine zusätzliche Konfiguration im Request vornehmen. Häufige Szenarien:

* Der Benutzer fragt „Hilf mir, nach neuen Ausstellungen in Shanghai in letzter Zeit zu suchen“ → Das Modell ruft die integrierte Websuche auf → Es bereitet die Ergebnisse zu einer Antwort auf.
* Der Benutzer fragt „Lies dieses PDF und schreibe dann eine Zusammenfassung“ → Das Modell ruft file\_read auf → Es schreibt eine Zusammenfassung.
* Der Benutzer hat Google Drive / GitHub / Notion usw. bereits in [Connections](https://platform.acedata.cloud/connections) autorisiert → Das Modell kann die entsprechenden MCP-Tools aufrufen, um deren Daten zu lesen und zu schreiben.

In NDJSON-/SSE-Streams werden Tool-Aufrufe durch die zwei Ereignistypen `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 du die Details von Tool-Aufrufen nicht im Frontend anzeigen möchtest, ignoriere einfach die Ereignistypen `tool_use` / `tool_result` / `card` / `citation`; die endgültige Ausgabe des Modells wird weiterhin über `text_delta` gestreamt.

`max_turns` kann die maximale Anzahl von selbstständigen Tool-Aufrufrunden des Modells in diesem Request begrenzen; der Bereich liegt bei 1–500, bei Auslassung ist der Standardwert 500. Wenn du ihn klein setzt (zum Beispiel `max_turns: 1`), kannst du eine einzelne Antwort erzwingen und jegliche Tool-Aufrufe verbieten.

## Asynchrone Ausführung und unbeaufsichtigte Autorisierung

Wenn dein Aufruf von einem Alarm-Webhook, CI/CD, Überwachungssystem oder einer anderen Hintergrundaufgabe stammt, kannst du `async: true` setzen, damit die Schnittstelle sofort eine Aufgaben-ID zurückgibt und die Ausführung im Hintergrund fortsetzt:

```json theme={null}
{
  "model": "gpt-5.5",
  "async": true,
  "question": "Mein Dienst hat Alarm ausgelöst, benachrichtige die WeChat-Gruppe „AceDataCloud团队“ über persönliches WeChat …"
}
```

Rückgabebeispiel:

```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 kannst du mit `action: retrieve` + `id` das Gesprächsergebnis abfragen; alternativ kannst du `callback_url` angeben, und nach Abschluss der Aufgabe wird die Plattform `{ status, answer, usage, error }` per POST an deine Callback-Adresse senden. `callback_url` muss `http` / `https` verwenden und darf nicht direkt mit `localhost` oder einer privaten IP-Literaladresse angegeben werden.

Bei Hintergrundaufgaben kann normalerweise niemand zur Bestätigung klicken. Wenn du möchtest, dass bestimmte Skills oder MCP-Server im unbeaufsichtigten Modus Aktionen wie Senden, Veröffentlichen oder Schreiben ausführen, übergib im Request-Body explizit eine Liste mit Vorabautorisierungen:

```json theme={null}
{
  "model": "gpt-5.5",
  "async": true,
  "allowed_skills": ["acedatacloud/personal-wechat"],
  "allowed_mcp_servers": [],
  "question": "Mein Dienst hat Alarm ausgelöst, benachrichtige die WeChat-Gruppe „AceDataCloud团队“ über persönliches WeChat …"
}
```

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 Vorabautorisierung aufgeführt sind, können im unbeaufsichtigten Modus weiterhin nur Vorschauen anzeigen, dry-run ausführen oder Schreibvorgänge ablehnen.

Wenn eine feinere Steuerung erforderlich ist, kannst du auch das gleichwertige Objekt `unattended_policy` verwenden:

```json theme={null}
{
  "unattended_policy": {
    "allowed_skills": ["acedatacloud/personal-wechat"],
    "allowed_mcp_servers": [],
    "expires_at": 1790000000
  }
}
```

Die Vorabautorisierung besteht aus diesen beiden Listen selbst: Eine leere Liste autorisiert keine Fähigkeiten, es ist kein zusätzliches Schalterfeld erforderlich.

Hinweis: Die Vorabautorisierung bedeutet nur: „Dieser Request erlaubt diesen Fähigkeiten, im unbeaufsichtigten Modus die manuelle Bestätigung zu überspringen.“ Der konkrete Skill muss weiterhin `--unattended-confirm` oder den entsprechenden Sicherheitsmechanismus unterstützen; andernfalls bleibt er bei dry-run und führt Schreibvorgänge nicht direkt aus.

## Pausierte Gespräche fortsetzen

Einige Tools veranlassen das Modell dazu, „dem Benutzer eine Rückfrage zu stellen“. Das Modell sendet dann ein `ask_user_question`-Ereignis, und 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": "Soll der generierte Bericht auf Chinesisch oder Englisch sein?",
  "options": ["Chinesisch", "Englisch"],
  "id": "f2f4b3e8-..."
}
```

Rendere dieses Ereignis im Frontend als Karte, damit der Benutzer eine Antwort auswählen kann, und starte dann mit derselben `id` den nächsten Request, wobei die Antwort über `tool_results` zurückgefüllt 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": "中文"
      }
    ]
  }'
```

`tool_use_id` im Request-Body **muss** vollständig mit `tool_id` zum Zeitpunkt der Pausierung übereinstimmen; bei Abweichung wird 400 zurückgegeben. Wenn gleichzeitig `tool_results` im Request vorhanden ist, werden `question` / `message` / `references` alle ignoriert.

Wenn der Benutzer beschließt, diese Frage aufzugeben, übergib einfach eine neue `question` / `message`; die Plattform markiert den pausierten Tool-Aufruf automatisch als „vom Benutzer übersprungen“.

## Gesprächsverwaltung (CRUD)

v2 bietet über das Feld `action` auf demselben Endpoint eine leichtgewichtige Gesprächsverwaltung, ohne dass eine zusätzliche API erforderlich ist.

### `action: retrieve` —— Eine Unterhaltung 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"
  }'
```

Gibt das vollständige Unterhaltungsdokument zurück (einschließlich des `messages`-Verlaufs, `model`, `title`, `tools_used` usw.).

### `action: retrieve_batch` —— Unterhaltungszusammenfassungen auflisten

```json theme={null}
{
  "action": "retrieve_batch",
  "model_group": "chatgpt",
  "limit": 20,
  "offset": 0
}
```

Gibt `{ items: [...], total }` zurück. **Zusammenfassungen enthalten keine `messages`** und eignen sich für Seitenleistenlisten; wenn ein Benutzer eine Unterhaltung öffnet, rufen Sie anschließend mit `action: retrieve` separat ihre vollständigen Nachrichten ab.

Optionale Filterparameter: `user_id`, `application_id`, `model_group`, `model`.

### `action: update` —— Titel ändern oder Verlauf überschreiben

```json theme={null}
{
  "action": "update",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "title": "杭州旅行计划"
}
```

`messages` kann ebenfalls übergeben werden, aber der Server führt eine strenge Schema-Validierung durch (muss die zusammengefasste `ToolUseContent`-Form haben); bei Nichtübereinstimmung wird 400 zurückgegeben. Im Allgemeinen wird empfohlen, dies nur zum Ändern von `title` zu verwenden.

### `action: delete` —— Eine Unterhaltung löschen

```json theme={null}
{
  "action": "delete",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}
```

Gibt `{ id, success: true }` zurück. Nach dem Löschen kann die Unterhaltung nicht wiederhergestellt werden; bestätigen Sie dies bitte vor dem Aufruf.

## Reibungslose Migration von v1

Wenn Sie bereits [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations) verwenden, erfordert die Migration zu v2 nahezu 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 verwendet haben (z. B. `gpt-3.5`, `gpt-4-browsing` usw.), wird beim Wechsel zu v2 empfohlen, auf moderne Modelle zu aktualisieren (z. B. `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` usw.).
3. Die Felder des NDJSON-Streams bleiben abwärtskompatibel: Jedes `text_delta`-Ereignis enthält weiterhin `delta_answer` und `id`, daher müssen Clients, die ursprünglich zeilenweise `delta_answer` analysieren, nicht geändert werden.

Nach der Migration können Sie bei Bedarf die neuen Fähigkeiten von v2 aktivieren (multimodales `message`, SSE, Tool-Aufrufe, `action`-CRUD) und schrittweise vorgehen.

## Fehlerbehandlung

Fehlerantworten haben ein einheitliches Format:

```json theme={null}
{
  "error": {
    "code": "chat_error",
    "message": "model service 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`: Der `authorization`-Header ist nicht korrekt.
* `404 not_found`: Die Unterhaltung, die der `id` bei `action: retrieve / update / delete` entspricht, existiert nicht.
* `429 too_many_requests`: Die Ratenbegrenzung wurde ausgelöst.
* `500 chat_error`: Ein Fehler des vorgelagerten LLM oder `completion_tokens=0` in dieser Runde (wird als nicht verbraucht behandelt und nicht berechnet).

In der Streaming-Antwort werden Fehler als Ereignis `{"type":"error","message":"..."}` gesendet, unmittelbar danach endet der Stream.

## Fazit

Die AI Chat v2 API ist abwärtskompatibel mit v1 und erweitert Gespräche von „einzelnen / mehreren Frage-Antwort-Runden“ zu „agentenbasierten, beobachtbaren Gesprächen“: multimodale Eingaben, Tool-Aufrufe, pausierbar / fortsetzbar, strukturierte Streaming-Ereignisse, integriertes CRUD. Für neue Integrationen wird empfohlen, direkt v2 zu verwenden; bestehende v1-Integrationen können schrittweise reibungslos migriert werden. Bei Fragen kontaktieren Sie bitte jederzeit unser technisches Support-Team.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.