> ## 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 Integracja Opis > AI Dialogue API guide - Ace Data Cloud AI Chat v2 API (`/aichat2/conversations`) to nowa generacja interfejsu rozmowy, będąca kompleksową aktualizacją [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Rozszerza on funkcjonalności v1, które były proste i obsługiwały wieloetapowe rozmowy, o: * **Wielomodalne wejście użytkownika**: poprzez zorganizowane pole `message` można bezpośrednio przesyłać tekst + obraz + pliki, bez potrzeby wcześniejszego używania `references`. * **Zautomatyzowane wywołania narzędzi**: wbudowany zestaw narzędzi do przeszukiwania sieci, zbierania danych z stron internetowych, odczytu plików itp., z możliwością podłączenia serwera MCP (Google Drive, Notion, Slack, GitHub itp.) z autoryzacją użytkownika, model może w jednym żądaniu wielokrotnie wywoływać narzędzia do realizacji złożonych zadań. * **Strukturalne zdarzenia strumieniowe**: poprzez `accept: text/event-stream` lub `application/x-ndjson` można uzyskać zdarzenia takie jak `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` itp., co ułatwia renderowanie w frontendzie według odpowiednich typów. * **Możliwość przerywania / wznawiania**: model wyśle zdarzenie `ask_user_question` i wstrzyma się, gdy potrzebuje dodatkowych informacji od użytkownika, a następne wywołanie może kontynuować, uzupełniając odpowiedzi przez `tool_results`. * **Nowe akcje CRUD**: na tym samym końcowym punkcie można wykonać `retrieve` / `retrieve_batch` / `update` / `delete` za pomocą pola `action`, bez potrzeby dodatkowego API do zarządzania sesjami. * **Ciągle aktualizowana lista modeli**: domyślnie dostępne modele to GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 i inne współczesne modele. Jednocześnie na poziomie ciała żądania **jest w pełni zgodne wstecz z v1**: wystarczy przesłać `model` + `question` (+ opcjonalnie `stateful` / `id` / `references` / `preset`), aby uzyskać równoważną odpowiedź JSON `{answer, id}` jak w v1, więc migracja z `/aichat/conversations` nie wymaga przepisania klienta, wystarczy zmienić ścieżkę na `/aichat2/conversations`. > Jeśli obecnie korzystasz z `/aichat/conversations`, stary interfejs nadal będzie dostępny, możesz migrować we własnym tempie. ## Proces aplikacji Aby korzystać z AI Chat v2 API, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę. **Jeden token API wystarczy do korzystania ze wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.** Pierwsze zgłoszenie otrzyma darmowy limit, aby móc korzystać z usługi; w przypadku niewystarczającego limitu można doładować saldo ogólne w [konsoli](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Podstawowe użycie Najprostszy sposób użycia jest całkowicie zgodny z v1: przekaż `model` + `question`, aby uzyskać `{answer, id}`. Przykład CURL: ```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": "Opowiedz w jednym zdaniu o AceDataCloud." }' ``` Wynik zwrotny: ```json theme={null} { "answer": "AceDataCloud to zintegrowana platforma API, która łączy w sobie główne modele AI i usługi wielomodalne, umożliwiająca deweloperom korzystanie z GPT, Claude, Gemini, Midjourney, Suno, Veo i innych usług za pomocą jednego klucza.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Przykład w Pythonie: ```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": "Opowiedz w jednym zdaniu o AceDataCloud.", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` Dostępne wartości `model` można zobaczyć bezpośrednio w rozwijanym menu w panelu Try po prawej stronie, a popularne kategorie obejmują: * 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` itp. * 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` itp. * 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` itp. * xAI: `grok-4` itp. * DeepSeek: `deepseek-v4-flash`, `deepseek-v3.2-exp`, `deepseek-r1-0528` itp. * Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` itp. * Zhipu: `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` itp. Szczegółowe zasady rozliczeń można znaleźć na karcie Pricing na stronie usługi. ## Wieloetapowe rozmowy Podobnie jak w v1, przekaż `stateful: true`, aby włączyć zapisywanie sesji, API zwróci `id`; w kolejnych żądaniach wystarczy przekazać `id`, aby kontynuować rozmowę, bez potrzeby samodzielnego zarządzania historią wiadomości. Pierwsze żądanie: ```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": "Zapamiętaj liczbę: 42." }' ``` Odpowiedź: ```json theme={null} { "answer": "Dobrze, zapamiętałem 42. Czy potrzebujesz, żebym coś z tym zrobił?", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Drugie żądanie, z tym samym `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": "Jaką liczbę kazałem ci zapamiętać?" }' ``` ```json theme={null} { "answer": "Liczba, którą kazałeś mi zapamiętać to 42.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` > `stateful` domyślnie jest `true`, pominięcie i jawne przekazanie `true` jest równoważne. Jeśli nie chcesz, aby serwer zapisywał tę rundę rozmowy, możesz jawnie ustawić `stateful: false`. ## Odpowiedź strumieniowa v2 obsługuje dwa formaty strumieniowe, wybierając według nagłówka `accept`: | Scenariusz | `accept` | Forma danych | | ---------------------------------------- | ------------------------------ | ----------------------------------------------------- | | Frontend Web / EventSource | `text/event-stream` | `data: {json}\n\n`, ostatnia linia `data: [DONE]\n\n` | | Serwer / CLI / Analiza strumieniowa Node | `application/x-ndjson` | Jeden obiekt JSON na linię | | Bez strumienia | `application/json` (domyślnie) | Zwraca jednorazowo `{answer, id}` | ### Przykład NDJSON ```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": "Przedstaw Hangzhou w trzech zdaniach.", } 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": # Zgodność z v1: fragmenty przyrostowe są również dostarczane przez pole delta_answer answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": print() print("zużycie =", event.get("usage")) ``` NDJSON każda linia to zorganizowane zdarzenie, najczęściej `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"} ``` ### Przykład SSE Na stronie przeglądarki użycie `EventSource` nie obsługuje niestandardowego ciała żądania, zaleca się użycie `fetch` + ręczne dzielenie na `\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: "Przedstaw Hangzhou w trzech zdaniach.", }), }); 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); } } ``` ### Typy zdarzeń strumieniowych | `type` | Znaczenie | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text_delta` | Przyrostowe fragmenty tekstu odpowiedzi asystenta. `content` to nowa treść; dla zgodności z v1, to samo zdarzenie zawiera również `delta_answer` (równe `content`) i `id`. | | `thinking` | Proces myślenia modelu (pojawia się tylko, gdy wybrany model ujawnia reasoning). | | `tool_use` | Model decyduje o użyciu narzędzia, zdarzenie zawiera `tool_id`, `tool_name`, `input`. | | `tool_result` | Wynik działania narzędzia, parowany z poprzednim `tool_use` przez `tool_id`, `is_error` wskazuje, czy wystąpił błąd. | | `card` | Strukturalna karta wygenerowana przez narzędzie (np. obraz, podgląd linku), odpowiednia do bezpośredniego renderowania. | | `citation` | Używane do uzupełnienia źródła URL odpowiadającego fragmentowi tekstu. | | `ask_user_question` | Model wysyła zapytanie do użytkownika o dodatkowe informacje, rozmowa wchodzi w stan `awaiting_user_input`, szczegóły w sekcji [Wznawianie wstrzymanej rozmowy](#wznawianie-wstrzymanej-rozmowy). | | `artifact` | Niezależny produkt wygenerowany przez model (np. bloki kodu, dokumenty), które można zapisać lub pobrać. | | `system_message` | Informacje systemowe (niezwiązane z treścią użytkownika i asystenta), używane tylko do wskazówek UI. | | `compact` | Zdarzenie, w którym wewnętrzny kontekst został skompresowany, nie wymaga specjalnego przetwarzania. | | `error` | Wystąpił błąd w tej rundzie, `message` opisuje treść błędu. | | `done` | Zakończenie odpowiedzi strumieniowej, zawiera `usage` (w tym `prompt_tokens` / `completion_tokens` / `total_tokens`) i `terminal_reason`. | Dla klientów, którzy interesują się tylko ostateczną odpowiedzią, połączenie wszystkich `text_delta` `content` jest równoważne `answer` w trybie `application/json`. ## Wprowadzenie multimodalne Jeśli dane wejściowe użytkownika zawierają obrazy lub pliki, przekaż `message` (tablica) zamiast `question`. Każdy element tablicy to blok treści: ```json theme={null} { "model": "gpt-5.4", "stateful": true, "message": [ { "type": "text", "text": "Ile kotów jest na tym obrazku?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } } ] } ``` Obsługiwane typy bloków: * `text` — Zwykły tekst, wymagane pole `text`. * `image_url` — Obraz, wymagane pole `image_url.url`. * `file_url` — Plik (PDF, CSV, TXT itp.), wymagane pole `file_url.url`. ### Związek z v1 `references` Aby zapewnić zgodność ze starszymi klientami, v2 nadal rozpoznaje pole `references: ["https://...", ...]`: * Sufiks URL to `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automatycznie przekształca w blok `image_url`; * Inne rozszerzenia przekształca w blok `file_url`; * Jeśli jednocześnie dostarczono `question`, należy go umieścić jako blok `text` na początku. Dlatego, jeśli chcesz tylko migrować z v1 i nie chcesz zmieniać ciała żądania, wystarczy zmienić ścieżkę na `/aichat2/conversations`, a oryginalne użycie `references` działa jak zwykle. Aby uzyskać bardziej precyzyjną kontrolę (na przykład umieścić wiele obrazów między tekstem lub gdy kolejność jest bardzo ważna), użyj bezpośrednio tablicy `message`. ## Wywołanie narzędzi i MCP Głównym punktem wzmocnienia v2 jest to, że model może samodzielnie wywoływać narzędzia do realizacji wieloetapowych zadań, **jest to domyślnie włączone**, nie wymaga dodatkowej konfiguracji w żądaniu od klienta. Typowe scenariusze: * Użytkownik pyta „Pomóż mi znaleźć nowe wystawy w Szanghaju” → model wywołuje wbudowane wyszukiwanie w sieci → porządkuje wyniki w odpowiedzi. * Użytkownik pyta „Przeczytaj ten PDF, a następnie napisz streszczenie” → model wywołuje `file_read` → pisze streszczenie. * Użytkownik autoryzował już Google Drive / GitHub / Notion itp. w [Connections](https://platform.acedata.cloud/connections) → model może wywołać odpowiednie narzędzie MCP do odczytu i zapisu danych. W strumieniu NDJSON / SSE, wywołania narzędzi są prezentowane przez dwa typy zdarzeń: `tool_use` i `tool_result`, na przykład: ```json theme={null} {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"Szanghaj 2026 wiosenne wystawy"},"id":"f2f4b3e8-..."} {"type":"tool_result","tool_id":"toolu_01ABCDEF","output":"...","is_error":false,"id":"f2f4b3e8-..."} {"type":"text_delta","content":"Obecnie","delta_answer":"Obecnie","id":"f2f4b3e8-..."} {"type":"text_delta","content":"Szanghaj","delta_answer":"Szanghaj","id":"f2f4b3e8-..."} ... ``` Jeśli nie chcesz wyświetlać szczegółów wywołania narzędzi na froncie, możesz zignorować zdarzenia `tool_use` / `tool_result` / `card` / `citation`, a ostateczny wynik modelu nadal będzie przekazywany przez `text_delta`. `max_turns` może ograniczyć, ile razy model może samodzielnie wywołać narzędzia w danym żądaniu, domyślny limit ustala platforma. Ustawienie go na małą wartość (na przykład `max_turns: 1`) może wymusić pojedynczą odpowiedź, bez dozwolonych wywołań narzędzi. ## Asynchroniczne wykonanie i autoryzacja bez nadzoru Jeśli twoje wywołanie pochodzi z webhooka alarmowego, CI/CD, systemu monitorowania lub innych zadań w tle, możesz ustawić `async: true`, aby interfejs natychmiast zwrócił identyfikator zadania, a w tle kontynuował wykonanie: ```json theme={null} { "model": "gpt-5.5", "async": true, "question": "Mój serwis zgłosił alarm, powiadom grupę WeChat „Zespół AceDataCloud”..." } ``` Przykład odpowiedzi: ```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" } ``` Następnie możesz użyć `action: retrieve` + `id`, aby sprawdzić wyniki sesji; możesz również podać `callback_url`, a po zakończeniu zadania platforma wyśle `{ status, answer, usage, error }` na twój adres zwrotny. `callback_url` musi używać `http` / `https` i nie może być bezpośrednio wpisany jako `localhost` lub prywatny adres IP. Zadania w tle zazwyczaj nie mają nikogo, kto mógłby kliknąć potwierdzenie. Jeśli chcesz, aby niektóre umiejętności lub serwery MCP wykonywały działania takie jak wysyłanie, publikowanie, zapisywanie itp. w trybie bez nadzoru, proszę wyraźnie przekazać listę wstępnych autoryzacji w ciele żądania: ```json theme={null} { "model": "gpt-5.5", "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "question": "Mój serwis zgłosił alarm, powiadom grupę WeChat „Zespół AceDataCloud”..." } ``` Wartości w `allowed_skills` to slug połączonych umiejętności; wartości w `allowed_mcp_servers` to slug połączonych serwerów MCP. Umiejętności / serwery MCP, które nie zostały wymienione w wstępnej autoryzacji, w trybie bez nadzoru mogą jedynie przeglądać, wykonywać dry-run lub odrzucać operacje zapisu. Jeśli potrzebujesz bardziej szczegółowej kontroli, możesz również użyć równoważnego obiektu `unattended_policy`: ```json theme={null} { "unattended_policy": { "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "expires_at": 1790000000 } } ``` Wstępna autoryzacja to po prostu te dwa listy: pusta lista oznacza brak autoryzacji do jakiejkolwiek funkcji, nie wymaga dodatkowego pola przełącznika. Uwaga: wstępna autoryzacja oznacza tylko „w tym żądaniu zezwól tym funkcjom na pominięcie potwierdzenia przez człowieka w trybie bez nadzoru”. Konkretna umiejętność nadal musi wspierać `--unattended-confirm` lub odpowiedni mechanizm bezpieczeństwa; w przeciwnym razie będzie kontynuować dry-run i nie wykona operacji zapisu. ## Wznowienie wstrzymanej rozmowy Niektóre narzędzia mogą sprawić, że model „zapyta użytkownika”, w tym momencie model wyśle zdarzenie `ask_user_question`, a rozmowa zostanie wstrzymana w stanie `awaiting_user_input`: ```json theme={null} { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", "question": "Jakiego języka chcesz użyć do wygenerowania raportu, chińskiego czy angielskiego?", "options": ["chiński", "angielski"], "id": "f2f4b3e8-..." } ``` Na froncie przekształć to zdarzenie w kartę, aby użytkownik mógł wybrać odpowiedź, a następnie użyj tego samego `id`, aby wysłać kolejne żądanie, wypełniając odpowiedź przez `tool_results`: ```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": "chiński" } ] }' ``` W ciele żądania `tool_use_id` **musi** być całkowicie zgodny z `tool_id` w momencie wstrzymania; niezgodność spowoduje zwrócenie 400. Gdy w żądaniu znajdują się jednocześnie `tool_results`, `question` / `message` / `references` zostaną zignorowane. Jeśli użytkownik zdecyduje się zrezygnować z tego pytania, wystarczy przesłać nowe `question` / `message`, a platforma automatycznie oznaczy wstrzymane wywołanie narzędzia jako „użytkownik pominął”. ## Zarządzanie sesjami (CRUD) v2 oferuje lekkie zarządzanie sesjami na tym samym punkcie końcowym za pomocą pola `action`, bez potrzeby otwierania dodatkowego API. ### `action: retrieve` — pobierz sesję ```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" }' ``` Zwróć pełną dokumentację rozmowy (w tym historię `messages`, `model`, `title`, `tools_used` itp.). ### `action: retrieve_batch` —— Wypisz podsumowanie rozmów ```json theme={null} { "action": "retrieve_batch", "model_group": "chatgpt", "limit": 20, "offset": 0 } ``` Zwróć `{ items: [...], total }`. **Podsumowanie nie zawiera `messages`**, nadaje się do listy w bocznym panelu; jeśli użytkownik otworzy daną rozmowę, użyj `action: retrieve`, aby pobrać jej pełne wiadomości. Opcjonalne parametry filtrujące: `user_id`, `application_id`, `model_group`, `model`. ### `action: update` —— Zmień tytuł lub przepisz historię ```json theme={null} { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "title": "Plan podróży do Hangzhou" } ``` `messages` również można przesłać, ale serwer przeprowadzi rygorystyczną walidację schematu (musi być w formie złożonej `ToolUseContent`), w przeciwnym razie zwróci 400. Zwykle zaleca się używać tylko do zmiany `title`. ### `action: delete` —— Usuń rozmowę ```json theme={null} { "action": "delete", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Zwróć `{ id, success: true }`. Po usunięciu nie można przywrócić, proszę potwierdzić przed wywołaniem. ## Płynna migracja z v1 Jeśli już korzystasz z [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), migracja do v2 prawie nie wymaga zmiany kodu: 1. Zmień URL z `https://api.acedata.cloud/aichat/conversations` na `https://api.acedata.cloud/aichat2/conversations`. 2. Jeśli wcześniej przesyłałeś nazwę modelu v1 (np. `gpt-3.5`, `gpt-4-browsing` itp.), przy przejściu na v2 zaleca się aktualizację do współczesnych modeli (np. `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro` itp.). 3. Pola strumienia NDJSON pozostają wstecznie kompatybilne: każde zdarzenie `text_delta` nadal zawiera `delta_answer` i `id`, więc klienci, którzy wcześniej analizowali `delta_answer` w wierszach, nie muszą wprowadzać zmian. Po migracji można włączyć nowe możliwości v2 (wielomodalne `message`, SSE, wywołania narzędzi, CRUD `action`), w miarę potrzeb. ## Obsługa błędów Błąd odpowiedzi jest jednolity: ```json theme={null} { "error": { "code": "chat_error", "message": "upstream LLM returned an error" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` Typowe błędy: * `400 bad_request`: brak wymaganych pól, `tool_use_id` niezgodne, nieprawidłowy schemat `messages` itp. * `401 invalid_token`: nagłówek `authorization` jest niepoprawny. * `404 not_found`: podczas `action: retrieve / update / delete` rozmowa o podanym `id` nie istnieje. * `429 too_many_requests`: przekroczono limit szybkości. * `500 chat_error`: błąd LLM w górę lub w tej rundzie `completion_tokens=0` (traktowane jako niezużyte, nie będzie opłat). W odpowiedziach strumieniowych błędy są wysyłane jako `{"type":"error","message":"..."}` zdarzenie, a następnie strumień zostanie zakończony. ## Wnioski API AI Chat v2, zachowując wsteczną kompatybilność z v1, przekształca rozmowy z „jedno- / wieloetapowych pytań i odpowiedzi” w „obserwowalne rozmowy z agentem”: wielomodalne wejścia, wywołania narzędzi, możliwość wstrzymania / wznowienia, strumieniowe zorganizowane zdarzenia, wbudowane CRUD. Zaleca się nowym użytkownikom bezpośrednie korzystanie z v2; istniejące integracje v1 można płynnie migrować w etapach. W razie jakichkolwiek pytań prosimy o kontakt z naszym zespołem wsparcia technicznego.