Skip to main content
AI Chat v2 API (/aichat2/conversations) — это новое поколение интерфейса для диалогов, являющееся полным обновлением AI Chat API. Он расширяет возможности v1, основанные на простоте и управлении многократными диалогами:
  • Мультимодальный ввод пользователя: через структурированное поле message можно передавать текст + изображения + файлы, без необходимости предварительного использования references.
  • Инструменты вызова в стиле Agent: встроенный набор инструментов для сетевого поиска, веб-скрапинга, чтения файлов и возможность подключения авторизованных серверов MCP (Google Drive, Notion, Slack, GitHub и др.), модель может многократно вызывать инструменты в одном запросе для выполнения сложных задач.
  • Структурированные потоковые события: через accept: text/event-stream или application/x-ndjson можно получить события text_delta, tool_use, tool_result, thinking, citation, card, artifact и др., что упрощает рендеринг на фронтенде по соответствующим типам.
  • Прерываемость / восстановимость: модель отправляет событие ask_user_question и приостанавливается, когда требуется дополнительная информация от пользователя, следующая вызов может продолжиться, если ответ будет возвращен через tool_results.
  • Новые действия CRUD: на одном и том же конечном пункте через поле action можно выполнять retrieve / retrieve_batch / update / delete, без необходимости в дополнительном API управления сессиями.
  • Постоянно обновляемый список моделей: по умолчанию доступны GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 и другие современные модели.
При этом на уровне тела запроса полностью обратно совместим с v1: достаточно передать model + question (+ опционально stateful / id / references / preset), чтобы получить эквивалентный ответ в формате JSON {answer, id}, поэтому миграция с /aichat/conversations не требует переписывания клиента, достаточно изменить путь на /aichat2/conversations.
Если вы в настоящее время используете /aichat/conversations, старый интерфейс останется доступным, и вы можете мигрировать в своем темпе.

Процесс подачи заявки

Чтобы использовать AI Chat v2 API, сначала перейдите в консоль Ace Data Cloud, чтобы получить ваш API Token и сохранить его на всякий случай. Если вы еще не вошли в систему или не зарегистрированы, вас автоматически перенаправят на страницу входа, чтобы пригласить вас зарегистрироваться и войти, после чего вы будете автоматически возвращены на текущую страницу. Один API Token позволяет вызывать все сервисы платформы, не нужно отдельно запрашивать для каждого сервиса. При первом запросе предоставляется бесплатный лимит, чтобы вы могли попробовать; при недостатке лимита можно пополнить общий баланс в консоли.
📘 Полная документация: AI Chat v2 API →

Основное использование

Самый простой способ использования полностью совпадает с v1: передайте model + question, чтобы получить {answer, id}. Пример CURL:
Возвращаемый результат:
Пример на Python:
Доступные значения model можно увидеть в выпадающем списке панели Try справа, среди часто используемых категорий:
  • 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 и др.
  • 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 и др.
  • 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 и др.
  • xAI: grok-4 и др.
  • DeepSeek: deepseek-v4-flash, deepseek-v3.2-exp, deepseek-r1-0528 и др.
  • Moonshot: kimi-k3, kimi-k2.6, kimi-k2.5 и др.
  • Zhipu: glm-5.1, glm-5, glm-5-turbo, glm-4.7, glm-4.5v и др.
Конкретные правила тарификации смотрите на странице сервиса в карточке Pricing.

Многократные диалоги

Как и в v1, передайте stateful: true, чтобы включить сохранение сессии, API вернет id; последующие запросы должны содержать этот id, чтобы продолжить диалог, без необходимости самостоятельно управлять историей сообщений. Первый запрос:
Возвращаемый результат:
Второй запрос, с тем же id:
stateful по умолчанию равно true, опущение и явная передача true эквивалентны. Если вы не хотите, чтобы сервер сохранял этот раунд диалога, вы можете явно установить stateful: false.

Потоковый ответ

v2 поддерживает два типа потокового формата, выбирая по заголовку accept:

Пример NDJSON

Каждая строка NDJSON — это структурированное событие, наиболее распространенное из которых — text_delta:

Пример SSE

На стороне браузера использование EventSource не поддерживает пользовательские тела запросов, рекомендуется использовать fetch + ручное разбиение по \n\n:

Типы потоковых событий

Для клиентов, которые интересуются только окончательным ответом, объединение всех text_delta content эквивалентно answer в режиме application/json.

Мультимодальный ввод

Если ввод пользователя содержит изображения или файлы, передайте message (массив) вместо question. Каждый элемент массива — это блок содержимого:
Поддерживаемые типы блоков:
  • text — обычный текст, обязательное поле text.
  • image_url — изображение, обязательное поле image_url.url.
  • file_url — файл (PDF, CSV, TXT и т.д.), обязательное поле file_url.url.

Связь с v1 references

Для совместимости со старыми клиентами, v2 по-прежнему распознает поле references: ["https://...", ...]:
  • URL суффикс jpg / jpeg / png / gif / bmp / webp / svg / heic / heif, автоматически преобразуется в блок image_url;
  • Другие расширения преобразуются в блок file_url;
  • Если также предоставлен question, то он будет передан как блок text перед остальным содержимым.
Таким образом, если вы хотите мигрировать только с v1 и не хотите изменять тело запроса, просто измените путь на /aichat2/conversations, оригинальное использование references будет работать как обычно. Для более тонкого контроля (например, чтобы разместить несколько изображений между текстами или если порядок имеет значение) используйте массив message.

Вызов инструментов и MCP

Основное улучшение v2 заключается в том, что модель может самостоятельно вызывать инструменты для выполнения многократных задач, это включено по умолчанию, и клиенту не нужно делать никаких дополнительных настроек в запросе. Распространенные сценарии:
  • Пользователь спрашивает «Помоги мне найти новые выставки в Шанхае» → модель вызывает встроенный веб-поиск → организует результаты в ответ.
  • Пользователь спрашивает «Прочитай этот PDF и напиши краткое содержание» → модель вызывает file_read → пишет краткое содержание.
  • Пользователь уже авторизовал Google Drive / GitHub / Notion и т.д. в Connections → модель может вызывать соответствующие инструменты MCP для чтения и записи данных.
В NDJSON / SSE потоке вызовы инструментов представлены через события tool_use и tool_result, например:
Если вы не хотите отображать детали вызова инструментов на фронтенде, просто игнорируйте события tool_use / tool_result / card / citation, модель в конечном итоге все равно будет выводить через text_delta. max_turns может ограничить, сколько раз модель может самостоятельно вызывать инструменты в этом запросе, максимальный лимит определяется платформой. Установите его на маленькое значение (например, max_turns: 1), чтобы принудительно получить единственный ответ без разрешения на вызов инструментов.

Асинхронное выполнение и безлюдное разрешение

Если ваш вызов исходит от вебхука оповещения, CI/CD, системы мониторинга или других фоновых задач, вы можете установить async: true, чтобы интерфейс немедленно вернул ID задачи, а фон продолжал выполнение:
Пример ответа:
Затем вы можете использовать action: retrieve + id, чтобы запросить результаты сессии; также можно предоставить callback_url, после завершения задачи платформа отправит { status, answer, usage, error } на ваш адрес обратного вызова. callback_url должен использовать http / https, и не может быть напрямую указан localhost или частный IP-адрес. Фоновые задачи обычно не требуют подтверждения от человека. Если вы хотите, чтобы некоторые навыки или MCP серверы выполняли действия отправки, публикации, записи и т.д. в безлюдном режиме, явно передайте список предварительных разрешений в теле запроса:
Значения в allowed_skills — это slug подключенных навыков; значения в allowed_mcp_servers — это slug подключенных MCP серверов. Навыки / MCP серверы, не включенные в предварительное разрешение, в безлюдном режиме все равно могут только просматривать, выполнять dry-run или отклонять выполнение операций записи. Если требуется более тонкий контроль, можно использовать эквивалентный объект unattended_policy:
Предварительное разрешение — это сами два списка: пустой список означает отсутствие разрешений, без дополнительных переключателей. Обратите внимание: предварительное разрешение только обозначает «в этом запросе разрешены эти возможности в безлюдном режиме без подтверждения человека». Конкретный навык все равно должен поддерживать --unattended-confirm или соответствующий механизм безопасности; в противном случае он продолжит выполнять dry-run и не выполнит операции записи напрямую.

Восстановление приостановленного диалога

Некоторые инструменты могут заставить модель «задать вопрос пользователю», в этом случае модель отправит событие ask_user_question, и диалог будет заморожен в состоянии awaiting_user_input:
На фронтенде это событие можно отобразить в виде карточки, чтобы пользователь выбрал ответ, а затем с тем же id отправить следующий запрос, заполнив ответ через tool_results:
В теле запроса tool_use_id должен полностью совпадать с tool_id во время приостановки; несоответствие приведет к ошибке 400. Когда в запросе одновременно присутствуют tool_results, question / message / references будут проигнорированы. Если пользователь решит отказаться от этого вопроса, просто передайте новый question / message, и платформа автоматически отметит приостановленный вызов инструмента как «пропущенный пользователем».

Управление сессиями (CRUD)

v2 предоставляет легкое управление сессиями через поле action на том же конечном пункте, без необходимости открывать дополнительный API.

action: retrieve — получение сессии

Возвращает полный документ беседы (включая историю messages, model, title, tools_used и т.д.).

action: retrieve_batch —— Список сводок бесед

Возвращает { items: [...], total }. Сводка не содержит messages, подходит для боковой панели; если пользователь откроет определённую беседу, затем с помощью action: retrieve можно отдельно получить её полные сообщения. Дополнительные параметры фильтрации: user_id, application_id, model_group, model.

action: update —— Изменить заголовок или переписать историю

messages также можно передать, но сервер будет проводить строгую проверку схемы (должен быть в форме свернутого ToolUseContent), несоответствие приведёт к ошибке 400. Обычно рекомендуется использовать только для изменения title.

action: delete —— Удалить беседу

Возвращает { id, success: true }. После удаления восстановить нельзя, пожалуйста, подтвердите перед вызовом.

Плавный переход с v1

Если вы уже используете /aichat/conversations, переход на v2 почти не требует изменения кода:
  1. Измените URL с https://api.acedata.cloud/aichat/conversations на https://api.acedata.cloud/aichat2/conversations.
  2. Если вы ранее использовали имена моделей v1 (например, gpt-3.5, gpt-4-browsing и т.д.), при переходе на v2 рекомендуется обновить до современных моделей (например, gpt-5.4, claude-opus-4-8, gemini-3.1-pro и т.д.).
  3. Поля потока NDJSON остаются обратно совместимыми: каждое событие text_delta по-прежнему содержит delta_answer и id, поэтому клиент, который изначально разбирал delta_answer построчно, не требует изменений.
После миграции можно по мере необходимости включать новые возможности v2 (мультимодальные message, SSE, вызовы инструментов, CRUD action), продвигаясь в своём темпе.

Обработка ошибок

Ошибки ответа унифицированы:
Распространённые ошибки:
  • 400 bad_request: отсутствуют обязательные поля, tool_use_id не совпадает, схема messages недействительна и т.д.
  • 401 invalid_token: заголовок authorization неверен.
  • 404 not_found: при action: retrieve / update / delete беседа с соответствующим id не существует.
  • 429 too_many_requests: превышен лимит запросов.
  • 500 chat_error: ошибка на стороне LLM или в текущем запросе completion_tokens=0 (обрабатывается как неиспользованный, плата не взимается).
В потоковых ответах ошибки отправляются как {"type":"error","message":"..."} событие, после чего поток завершится.

Заключение

API AI Chat v2, сохраняя обратную совместимость с v1, обновляет беседы с «однократного / многократного вопроса» на «агентные наблюдаемые беседы»: мультимодальный ввод, вызовы инструментов, возможность приостановки / восстановления, потоковые структурированные события, встроенный CRUD. Рекомендуется новым пользователям сразу использовать v2; существующие интеграции v1 могут плавно перейти поэтапно. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.