Przejdź do głównej treści
AI Chat v2 API (/aichat2/conversations) jest interfejsem konwersacyjnym nowej generacji i kompleksowo ulepszoną wersją AI Chat API. Na podstawie prostoty v1 i zarządzanych wieloturowych rozmów rozszerza on:
  • Wielomodalne dane wejściowe użytkownika: poprzez ustrukturyzowane pole message można bezpośrednio przekazywać bloki tekstu + obrazów + plików, bez konieczności wcześniejszego pośredniego dołączania ich za pomocą references.
  • Wywoływanie narzędzi w stylu Agent: wbudowany zestaw narzędzi do wyszukiwania w internecie, pobierania stron internetowych, odczytu plików itp. oraz możliwość podłączenia autoryzowanych przez użytkownika serwerów MCP (Google Drive, Notion, Slack, GitHub itd.); model może w jednym żądaniu autonomicznie wielokrotnie wywoływać narzędzia, aby wykonywać złożone zadania.
  • Ustrukturyzowane zdarzenia strumieniowe: za pomocą 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. dla kolejnych tokenów, co ułatwia osobne renderowanie ich według odpowiednich typów w interfejsie frontendowym.
  • Możliwość przerwania / wznowienia: gdy model potrzebuje, aby użytkownik uzupełnił informacje, wyśle zdarzenie ask_user_question i wstrzyma działanie; przy następnym wywołaniu można kontynuować, uzupełniając odpowiedź przez tool_results.
  • Nowe działania CRUD: w tym samym endpointcie można wykonywać retrieve / retrieve_batch / update / delete za pomocą pola action, bez potrzeby dodatkowego API do zarządzania rozmowami.
  • Stale aktualizowana lista modeli: domyślnie obsługiwane są współczesne modele, takie jak GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 itd.
Jednocześnie na poziomie body żądania jest on w pełni wstecznie kompatybilny z v1: wystarczy przekazać model + question (+ opcjonalnie stateful / id / references / preset), aby uzyskać odpowiedź JSON {answer, id} równoważną z v1. Dlatego migracja z /aichat/conversations nie wymaga przepisywania klienta — wystarczy zmienić ścieżkę na /aichat2/conversations.
Jeśli obecnie korzystasz z /aichat/conversations, stary interfejs nadal będzie dostępny, więc możesz migrować we własnym tempie.

Proces składania wniosku

Aby korzystać z AI Chat v2 API, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go na później. Jeśli nie jesteś jeszcze zalogowany(-a) lub zarejestrowany(-a), nastąpi automatyczne przekierowanie na stronę logowania, gdzie zostaniesz zaproszony(-a) do rejestracji i zalogowania się; po zakończeniu automatycznie wrócisz na bieżącą stronę. Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez konieczności osobnego składania wniosku dla każdej usługi. Przy pierwszym wniosku otrzymasz darmowy limit, który umożliwi bezpłatne testowanie; gdy limit będzie niewystarczający, możesz doładować wspólne saldo w konsoli.
📘 Pełna dokumentacja: AI Chat v2 API →

Podstawowe użycie

Najprostszy sposób użycia jest całkowicie taki sam jak w v1: przekaż model + question, aby otrzymać {answer, id}. Przykład CURL:
Wynik zwracany:
Przykład Python:
Dostępne wartości model można zobaczyć bezpośrednio na liście rozwijanej panelu Try po prawej stronie; często używane 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 itd.
  • 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 itd.
  • 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 itd.
  • xAI: grok-4 itd.
  • DeepSeek: deepseek-v4-pro, deepseek-v4.1-flash, deepseek-v4-flash, deepseek-v3.2-exp, deepseek-r1-0528 itd.
  • Moonshot: kimi-k3.1-pro, kimi-k3, kimi-k2.6, kimi-k2.5 itd.
  • Zhipu: glm-5.3, glm-5.2, glm-5.1, glm-5, glm-5-turbo, glm-4.7, glm-4.5v itd.
Szczegółowe zasady rozliczania znajdują się na karcie Pricing na stronie usługi.

Rozmowy wieloturowe

Tak jak w v1, przekaż stateful: true, aby włączyć zapisywanie rozmowy; API zwróci id; w kolejnych żądaniach wystarczy przekazać z powrotem id, aby kontynuować rozmowę, bez samodzielnego utrzymywania historii messages. Pierwsze żądanie:
Zwraca:
Drugie żądanie, z tym samym id:
stateful domyślnie ma wartość true; pominięcie go jest równoważne z jawnym przekazaniem true. Jeśli nie chcesz, aby serwer zapisywał tę turę rozmowy, możesz jawnie ustawić stateful: false.

Odpowiedzi strumieniowe

v2 obsługuje dwa formaty strumieniowe, wybierane za pomocą nagłówka accept:

Przykład NDJSON

Każda linia NDJSON jest ustrukturyzowanym zdarzeniem; najczęściej występuje text_delta:

Przykład SSE

EventSource po stronie przeglądarki nie obsługuje niestandardowego treści żądania, zaleca się użycie fetch + ręczne analizowanie przez dzielenie według \n\n:

Typy zdarzeń strumieniowych

W przypadku klientów, których interesuje tylko końcowa odpowiedź, połączenie wszystkich content z text_delta jest równoważne z answer w trybie application/json.

Wejście multimodalne

Jeśli dane wejściowe użytkownika zawierają obrazy lub pliki, przekaż message (tablicę) zamiast question. Każdy element tablicy jest blokiem zawartości:
Obsługiwane typy bloków:
  • text — zwykły tekst, wymagane pole text.
  • image_url — obraz, wymagane image_url.url.
  • file_url — plik (PDF, CSV, TXT itp.), wymagane file_url.url.

Relacja z references w v1

Aby zachować zgodność ze starszymi klientami, v2 nadal rozpoznaje pole references: ["https://...", ...]:
  • Jeśli sufiks URL to jpg / jpeg / png / gif / bmp / webp / svg / heic / heif, automatycznie konwertuj na blok image_url;
  • Inne rozszerzenia konwertuj na blok file_url;
  • Jeśli jednocześnie podano question, umieść je na początku jako blok text.
Dlatego jeśli chcesz tylko przejść z v1 i nie chcesz zmieniać body żądania, wystarczy zmienić ścieżkę na /aichat2/conversations, a dotychczasowe użycie references nadal działa. Jeśli potrzebujesz bardziej precyzyjnej kontroli (na przykład umieszczania wielu obrazów pomiędzy tekstem albo gdy kolejność jest bardzo ważna), użyj bezpośrednio tablicy message.

Wywoływanie narzędzi i MCP

Kluczowym ulepszeniem v2 jest to, że model może samodzielnie wywoływać narzędzia, aby realizować zadania wieloetapowe, jest to domyślnie włączone i nie wymaga żadnej dodatkowej konfiguracji po stronie klienta w żądaniu. Typowe scenariusze:
  • Użytkownik pyta „Pomóż mi wyszukać, jakie nowe wystawy są ostatnio w Szanghaju” → model wywołuje wbudowane web search → porządkuje wyniki w odpowiedź.
  • Użytkownik pyta „Przeczytaj ten PDF, a następnie napisz podsumowanie” → model wywołuje file_read → pisze podsumowanie.
  • Użytkownik autoryzował już Google Drive / GitHub / Notion itd. w Connections → model może wywoływać odpowiednie narzędzia MCP do odczytu i zapisu ich danych.
W strumieniu NDJSON / SSE wywołania narzędzi są przedstawiane przez dwa typy zdarzeń: tool_use i tool_result, na przykład:
Jeśli nie chcesz wyświetlać szczegółów wywołań narzędzi w frontendzie, wystarczy ignorować zdarzenia typu tool_use / tool_result / card / citation, a końcowe wyjście modelu nadal będzie przesyłane strumieniowo przez text_delta. max_turns może ograniczyć maksymalną liczbę rund samodzielnego wywoływania narzędzi przez model w tym żądaniu; zakres wynosi 1–500, a domyślnie jest to 500, jeśli pole zostanie pominięte. Ustawienie małej wartości (na przykład max_turns: 1) może wymusić jednorazową odpowiedź i nie zezwolić na żadne wywołania narzędzi.

Wykonanie asynchroniczne i autoryzacja bez nadzoru

Jeśli Twoje wywołanie pochodzi z alertu Webhook, CI/CD, systemu monitoringu lub innego zadania działającego w tle, możesz ustawić async: true, aby interfejs natychmiast zwrócił ID zadania, a wykonywanie było kontynuowane w tle:
Przykład odpowiedzi:
Następnie możesz użyć action: retrieve + id, aby sprawdzić wynik rozmowy; możesz też podać callback_url, a po ukończeniu zadania platforma wyśle metodą POST { status, answer, usage, error } na Twój adres zwrotny. callback_url musi używać http / https i nie może bezpośrednio zawierać localhost ani literałowego adresu prywatnego IP. Zadania działające w tle zwykle nie mają osoby, która może kliknąć potwierdzenie. Jeśli chcesz, aby niektóre Skill lub MCP Server wykonywały działania takie jak wysyłanie, publikowanie czy zapisywanie w trybie bez nadzoru, jawnie przekaż listę wstępnej autoryzacji w body żądania:
Wartości w allowed_skills to slug podłączonych Skill; wartości w allowed_mcp_servers to slug podłączonych MCP Server. Skill / MCP Server niewymienione we wstępnej autoryzacji mogą w trybie bez nadzoru nadal tylko wyświetlać podgląd, wykonywać dry-run lub odmawiać wykonania operacji zapisu. Jeśli potrzebujesz bardziej szczegółowej kontroli, możesz również użyć równoważnego obiektu unattended_policy:
Wstępna autoryzacja to same te dwie listy: pusta lista oznacza brak autoryzacji dla jakichkolwiek możliwości, bez potrzeby stosowania dodatkowego pola przełącznika. Uwaga: wstępna autoryzacja oznacza jedynie „to żądanie pozwala tym możliwościom pominąć ręczne potwierdzenie w trybie bez nadzoru”. Konkretny Skill nadal musi obsługiwać --unattended-confirm albo odpowiedni mechanizm bezpieczeństwa; w przeciwnym razie będzie nadal wykonywał dry-run i nie wykona bezpośrednio operacji zapisu.

Wznawianie wstrzymanych rozmów

Niektóre narzędzia powodują, że model „zadaje użytkownikowi pytanie zwrotne”; wówczas model wysyła zdarzenie ask_user_question, a rozmowa zostaje zamrożona w stanie awaiting_user_input:
W frontendzie wyrenderuj to zdarzenie jako kartę, aby użytkownik wybrał odpowiedź, a następnie użyj tego samego id, aby wysłać kolejne żądanie i uzupełnić odpowiedź przez tool_results:
tool_use_id w body żądania musi być dokładnie zgodne z tool_id w momencie wstrzymania; niezgodność zwróci 400. Gdy w żądaniu jednocześnie występuje tool_results, question / message / references zostaną zignorowane. Jeśli użytkownik zdecyduje się porzucić to pytanie, wystarczy bezpośrednio przekazać nowe question / message, a platforma automatycznie oznaczy wstrzymane wywołanie narzędzia jako „pominięte przez użytkownika”.

Zarządzanie rozmowami (CRUD)

v2 zapewnia lekkie zarządzanie rozmowami za pomocą pola action w tym samym endpointzie, bez potrzeby udostępniania dodatkowego API.

action: retrieve —— pobranie rozmowy

Zwraca kompletny dokument rozmowy (w tym historię messages, model, title, tools_used itd.).

action: retrieve_batch —— wyświetlenie podsumowań rozmów

Zwraca { items: [...], total }. Podsumowania nie zawierają messages, dlatego nadają się do listy na pasku bocznym; jeśli użytkownik otworzy daną rozmowę, użyj następnie action: retrieve, aby osobno pobrać jej pełne wiadomości. Opcjonalne parametry filtrowania: user_id, application_id, model_group, model.

action: update —— zmiana tytułu lub nadpisanie historii

Można również przekazać messages, ale serwer przeprowadzi rygorystyczną walidację schematu (musi to być zwinięta postać ToolUseContent); w przypadku niezgodności zwróci 400. Zazwyczaj zaleca się używanie tego wyłącznie do zmiany title.

action: delete —— usunięcie rozmowy

Zwraca { id, success: true }. Po usunięciu nie można jej odzyskać, dlatego przed wywołaniem należy się upewnić.

Płynna migracja z v1

Jeśli korzystasz już z /aichat/conversations, migracja do v2 prawie nie wymaga zmian w kodzie:
  1. Zmień URL z https://api.acedata.cloud/aichat/conversations na https://api.acedata.cloud/aichat2/conversations.
  2. Jeśli wcześniej przekazywałeś nazwy modeli v1 (takie jak gpt-3.5, gpt-4-browsing itd.), podczas przejścia na v2 zaleca się aktualizację do współczesnych modeli (takich jak gpt-5.4, claude-opus-4-8, gemini-3.1-pro-preview itd.).
  3. Pola strumienia NDJSON zachowują kompatybilność wsteczną: każde zdarzenie text_delta nadal zawiera delta_answer i id, dlatego klienci, które pierwotnie parsowały wiersz po wierszu delta_answer, nie wymagają zmian.
Po migracji można w razie potrzeby włączyć nowe możliwości v2 (multimodalne message, SSE, wywoływanie narzędzi, CRUD action) i wdrażać je we własnym tempie.

Obsługa błędów

Odpowiedzi błędów mają jednolity format:
Typowe błędy:
  • 400 bad_request: brak wymaganych pól, niezgodne tool_use_id, nieprawidłowy schemat messages itd.
  • 401 invalid_token: nagłówek authorization jest nieprawidłowy.
  • 404 not_found: podczas action: retrieve / update / delete rozmowa odpowiadająca id nie istnieje.
  • 429 too_many_requests: uruchomiono ograniczenie szybkości.
  • 500 chat_error: błąd nadrzędnego LLM lub completion_tokens=0 w tej turze (traktowane jako niezużyte, opłata nie zostanie naliczona).
W odpowiedzi strumieniowej błędy są wysyłane jako zdarzenia {"type":"error","message":"..."}, po czym strumień natychmiast się zakończy.

Wnioski

AI Chat v2 API, zachowując kompatybilność wsteczną z v1, podnosi rozmowy z „jednoturowych / wieloturowych pytań i odpowiedzi” do „obserwowalnych rozmów agentowych”: wejście multimodalne, wywoływanie narzędzi, możliwość wstrzymania / wznowienia, strumieniowe ustrukturyzowane zdarzenia, wbudowany CRUD. Zaleca się, aby nowe integracje bezpośrednio korzystały z v2; istniejące integracje v1 mogą być płynnie migrowane etapami. W razie jakichkolwiek pytań prosimy o kontakt z naszym zespołem wsparcia technicznego.