Skip to main content
AI Chat v2 API (/aichat2/conversations) to nowa generacja interfejsu rozmowy, będąca kompleksową aktualizacją AI Chat API. 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, aby uzyskać swój token API, który należy zachować na przyszłość. 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.
📘 Pełna dokumentacja: AI Chat v2 API →

Podstawowe użycie

Najprostszy sposób użycia jest całkowicie zgodny z v1: przekaż model + question, aby uzyskać {answer, id}. Przykład CURL:
Wynik zwrotny:
Przykład w Pythonie:
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:
Odpowiedź:
Drugie żądanie, z tym samym id:
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:

Przykład NDJSON

NDJSON każda linia to zorganizowane zdarzenie, najczęściej text_delta:

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:

Typy zdarzeń strumieniowych

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:
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 → 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:
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:
Przykład odpowiedzi:
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:
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:
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:
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:
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ę

Zwróć pełną dokumentację rozmowy (w tym historię messages, model, title, tools_used itp.).

action: retrieve_batch —— Wypisz podsumowanie rozmów

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ę

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ę

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, 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:
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.