Skip to main content
Die AI Chat v2 API (/aichat2/conversations) ist die nächste Generation der Dialogschnittstelle und eine umfassende Upgrade-Version der AI Chat API. Sie erweitert die v1, die einfache, gehostete Mehrfachdialoge unterstützt, 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: Über 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 retrieve / retrieve_batch / update / delete über das action-Feld ausgeführt werden, ohne dass eine zusätzliche Sitzungsmanagement-API erforderlich ist.
  • 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, um Ihr API-Token zu erhalten, das Sie zur Sicherheit aufbewahren sollten. 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 Ihr allgemeines Guthaben aufladen.
📘 Vollständige Dokumentation: AI Chat v2 API →

Grundlegende Nutzung

Die einfachste Verwendung ist identisch mit v1: Übertragen Sie model + question, um {answer, id} zu erhalten. CURL-Beispiel:
Rückgabe:
Python-Beispiel:
Verfügbare model-Werte können im Dropdown-Menü im rechten Try-Bereich direkt eingesehen 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.

Mehrfachdialog

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:
Rückgabe:
Zweite Anfrage, mit der gleichen id:
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:

NDJSON Beispiel

NDJSON jede Zeile ist ein strukturiertes Ereignis, am häufigsten ist text_delta:

SSE Beispiel

Im Browser verwendet EventSource keine benutzerdefinierten Anforderungskörper, es wird empfohlen, fetch + manuelles Zerlegen nach \n\n zu verwenden:

Streaming-Ereignistypen

Für Clients, die nur an der endgültigen Antwort interessiert sind, ist das Zusammenfügen aller text_delta-content 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:
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 → fasst die Ergebnisse in einer Antwort zusammen.
  • Der Benutzer fragt: „Lies dieses PDF und schreibe eine Zusammenfassung“ → Modell ruft file_read auf → schreibt die Zusammenfassung.
  • Der Benutzer hat in Connections Google Drive / GitHub / Notion usw. autorisiert → Modell kann die entsprechenden MCP-Tools aufrufen, um deren Daten zu lesen und zu schreiben.
In NDJSON / SSE-Streams werden Werkzeugaufrufe durch die Ereignisse tool_use und tool_result dargestellt, zum Beispiel:
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:
Beispielantwort:
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:
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:
Die vorab autorisierte Liste sind diese beiden Listen selbst: Eine leere Liste bedeutet, dass keine Fähigkeiten autorisiert sind, ohne dass zusätzliche Schalterfelder erforderlich sind. Hinweis: Die vorab autorisierte Liste 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 können das Modell „den Benutzer fragen“ lassen, das Modell sendet dann ein ask_user_question Ereignis, das Gespräch wird im Status awaiting_user_input eingefroren:
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:
Im Anfragekörper muss tool_use_id genau mit dem 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 automatisch den pausierten Werkzeugaufruf als „vom Benutzer übersprungen“ markieren.

Sitzungsmanagement (CRUD)

v2 bietet auf demselben Endpunkt über das Feld action ein leichtgewichtiges Sitzungsmanagement, ohne dass eine zusätzliche API erforderlich ist.

action: retrieve — Eine Sitzung abrufen

Geben Sie das vollständige Sitzungsdokument zurück (einschließlich messages Verlauf, model, title, tools_used usw.).

action: retrieve_batch —— Listet die Sitzungszusammenfassungen auf

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

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

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 verwenden, erfordert die Migration zu v2 fast keine Codeänderungen:
  1. Ändern Sie die URL von https://api.acedata.cloud/aichat/conversations in 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:
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 Streaming-Ereignisse, 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.