> ## 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 интеграция > AI Dialogue API guide - Ace Data Cloud AI Chat v2 API (`/aichat2/conversations`) — это новое поколение интерфейса для диалогов, являющееся полным обновлением [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Он расширяет возможности 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](https://platform.acedata.cloud/console/applications), чтобы получить ваш API Token и сохранить его на всякий случай. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Если вы еще не вошли в систему или не зарегистрированы, вас автоматически перенаправят на страницу входа, чтобы пригласить вас зарегистрироваться и войти, после чего вы будете автоматически возвращены на текущую страницу. **Один API Token позволяет вызывать все сервисы платформы, не нужно отдельно запрашивать для каждого сервиса.** При первом запросе предоставляется бесплатный лимит, чтобы вы могли попробовать; при недостатке лимита можно пополнить общий баланс в [консоли](https://platform.acedata.cloud/console/coin). > 📘 Полная документация: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Основное использование Самый простой способ использования полностью совпадает с v1: передайте `model` + `question`, чтобы получить `{answer, id}`. Пример 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": "Представьте AceDataCloud одним предложением." }' ``` Возвращаемый результат: ```json theme={null} { "answer": "AceDataCloud — это единая API-платформа, объединяющая основные AI-модели и мультимодальные сервисы, позволяющая разработчикам вызывать услуги от GPT, Claude, Gemini, Midjourney, Suno, Veo и других с помощью одного ключа.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Пример на Python: ```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": "Представьте AceDataCloud одним предложением.", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` Доступные значения `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`, чтобы продолжить диалог, без необходимости самостоятельно управлять историей сообщений. Первый запрос: ```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": "Запомни число: 42." }' ``` Возвращаемый результат: ```json theme={null} { "answer": "Хорошо, я запомнил 42. Что мне с ним сделать?", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Второй запрос, с тем же `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": "Какое число я только что попросил тебя запомнить?" }' ``` ```json theme={null} { "answer": "Число, которое ты попросил меня запомнить, это 42.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` > `stateful` по умолчанию равно `true`, опущение и явная передача `true` эквивалентны. Если вы не хотите, чтобы сервер сохранял этот раунд диалога, вы можете явно установить `stateful: false`. ## Потоковый ответ v2 поддерживает два типа потокового формата, выбирая по заголовку `accept`: | Сцена | `accept` | Форма данных | | --------------------------------------- | --------------------------------- | ------------------------------------------------------- | | Веб фронт / EventSource | `text/event-stream` | `data: {json}\n\n`, последняя строка `data: [DONE]\n\n` | | Сервер / CLI / Node потоковая обработка | `application/x-ndjson` | Один JSON объект на строку | | Не требуется потоковый | `application/json` (по умолчанию) | Одноразовый ответ `{answer, id}` | ### Пример 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": "Представьте Ханчжоу тремя предложениями.", } 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": # Для совместимости с v1: инкрементальные фрагменты также предоставляются через поле delta_answer answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": print() print("usage =", event.get("usage")) ``` Каждая строка NDJSON — это структурированное событие, наиболее распространенное из которых — `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"} ``` ### Пример SSE На стороне браузера использование `EventSource` не поддерживает пользовательские тела запросов, рекомендуется использовать `fetch` + ручное разбиение по `\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: "Представьте Ханчжоу тремя предложениями.", }), }); 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); } } ``` ### Типы потоковых событий | `type` | Значение | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text_delta` | Инкремальные текстовые фрагменты ответа помощника. `content` — это новый контент; для совместимости с v1, то же событие также содержит `delta_answer` (равный `content`) и `id`. | | `thinking` | Процесс размышления модели (появляется только если выбранная модель раскрывает reasoning). | | `tool_use` | Модель решает вызвать инструмент, событие содержит `tool_id`, `tool_name`, `input`. | | `tool_result` | Результат выполнения инструмента, сопоставляется с предыдущим `tool_use` по `tool_id`, `is_error` указывает, произошла ли ошибка. | | `card` | Структурированная карточка, созданная инструментом (например, изображение, предварительный просмотр ссылки), подходит для прямого рендеринга. | | `citation` | Используется для дополнения источника URL соответствующего текстового фрагмента. | | `ask_user_question` | Модель отправляет запрос пользователю на дополнительную информацию, диалог переходит в состояние `awaiting_user_input`, см. ниже [Восстановление приостановленного диалога](#восстановление-приостановленного-диалога). | | `artifact` | Независимый продукт, созданный моделью (например, блоки кода, документы), может быть сохранен или загружен. | | `system_message` | Системное сообщение (не содержимое пользователя и помощника), используется только для UI подсказок. | | `compact` | Событие сжатого внутреннего контекста, не требует специальной обработки. | | `error` | Ошибка произошла в этом раунде, `message` описывает содержание ошибки. | | `done` | Конец потокового ответа, содержит `usage` (включая `prompt_tokens` / `completion_tokens` / `total_tokens`) и `terminal_reason`. | Для клиентов, которые интересуются только окончательным ответом, объединение всех `text_delta` `content` эквивалентно `answer` в режиме `application/json`. ## Мультимодальный ввод Если ввод пользователя содержит изображения или файлы, передайте `message` (массив) вместо `question`. Каждый элемент массива — это блок содержимого: ```json theme={null} { "model": "gpt-5.4", "stateful": true, "message": [ { "type": "text", "text": "Сколько котов на этом изображении?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } } ] } ``` Поддерживаемые типы блоков: * `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](https://platform.acedata.cloud/connections) → модель может вызывать соответствующие инструменты MCP для чтения и записи данных. В NDJSON / SSE потоке вызовы инструментов представлены через события `tool_use` и `tool_result`, например: ```json theme={null} {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"Шанхай 2026 весенние выставки"},"id":"f2f4b3e8-..."} {"type":"tool_result","tool_id":"toolu_01ABCDEF","output":"...","is_error":false,"id":"f2f4b3e8-..."} {"type":"text_delta","content":"в настоящее время","delta_answer":"в настоящее время","id":"f2f4b3e8-..."} {"type":"text_delta","content":"Шанхай","delta_answer":"Шанхай","id":"f2f4b3e8-..."} ... ``` Если вы не хотите отображать детали вызова инструментов на фронтенде, просто игнорируйте события `tool_use` / `tool_result` / `card` / `citation`, модель в конечном итоге все равно будет выводить через `text_delta`. `max_turns` может ограничить, сколько раз модель может самостоятельно вызывать инструменты в этом запросе, максимальный лимит определяется платформой. Установите его на маленькое значение (например, `max_turns: 1`), чтобы принудительно получить единственный ответ без разрешения на вызов инструментов. ## Асинхронное выполнение и безлюдное разрешение Если ваш вызов исходит от вебхука оповещения, CI/CD, системы мониторинга или других фоновых задач, вы можете установить `async: true`, чтобы интерфейс немедленно вернул ID задачи, а фон продолжал выполнение: ```json theme={null} { "model": "gpt-5.5", "async": true, "question": "Моя служба сработала, уведомите группу WeChat «AceDataCloud команда»…" } ``` Пример ответа: ```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" } ``` Затем вы можете использовать `action: retrieve` + `id`, чтобы запросить результаты сессии; также можно предоставить `callback_url`, после завершения задачи платформа отправит `{ status, answer, usage, error }` на ваш адрес обратного вызова. `callback_url` должен использовать `http` / `https`, и не может быть напрямую указан `localhost` или частный IP-адрес. Фоновые задачи обычно не требуют подтверждения от человека. Если вы хотите, чтобы некоторые навыки или MCP серверы выполняли действия отправки, публикации, записи и т.д. в безлюдном режиме, явно передайте список предварительных разрешений в теле запроса: ```json theme={null} { "model": "gpt-5.5", "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "question": "Моя служба сработала, уведомите группу WeChat «AceDataCloud команда»…" } ``` Значения в `allowed_skills` — это slug подключенных навыков; значения в `allowed_mcp_servers` — это slug подключенных MCP серверов. Навыки / MCP серверы, не включенные в предварительное разрешение, в безлюдном режиме все равно могут только просматривать, выполнять dry-run или отклонять выполнение операций записи. Если требуется более тонкий контроль, можно использовать эквивалентный объект `unattended_policy`: ```json theme={null} { "unattended_policy": { "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], "expires_at": 1790000000 } } ``` Предварительное разрешение — это сами два списка: пустой список означает отсутствие разрешений, без дополнительных переключателей. Обратите внимание: предварительное разрешение только обозначает «в этом запросе разрешены эти возможности в безлюдном режиме без подтверждения человека». Конкретный навык все равно должен поддерживать `--unattended-confirm` или соответствующий механизм безопасности; в противном случае он продолжит выполнять dry-run и не выполнит операции записи напрямую. ## Восстановление приостановленного диалога Некоторые инструменты могут заставить модель «задать вопрос пользователю», в этом случае модель отправит событие `ask_user_question`, и диалог будет заморожен в состоянии `awaiting_user_input`: ```json theme={null} { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", "question": "Какой язык вы хотите для генерируемого отчета, китайский или английский?", "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` На фронтенде это событие можно отобразить в виде карточки, чтобы пользователь выбрал ответ, а затем с тем же `id` отправить следующий запрос, заполнив ответ через `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": "中文" } ] }' ``` В теле запроса `tool_use_id` **должен** полностью совпадать с `tool_id` во время приостановки; несоответствие приведет к ошибке 400. Когда в запросе одновременно присутствуют `tool_results`, `question` / `message` / `references` будут проигнорированы. Если пользователь решит отказаться от этого вопроса, просто передайте новый `question` / `message`, и платформа автоматически отметит приостановленный вызов инструмента как «пропущенный пользователем». ## Управление сессиями (CRUD) v2 предоставляет легкое управление сессиями через поле `action` на том же конечном пункте, без необходимости открывать дополнительный API. ### `action: retrieve` — получение сессии ```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" }' ``` Возвращает полный документ беседы (включая историю `messages`, `model`, `title`, `tools_used` и т.д.). ### `action: retrieve_batch` —— Список сводок бесед ```json theme={null} { "action": "retrieve_batch", "model_group": "chatgpt", "limit": 20, "offset": 0 } ``` Возвращает `{ items: [...], total }`. **Сводка не содержит `messages`**, подходит для боковой панели; если пользователь откроет определённую беседу, затем с помощью `action: retrieve` можно отдельно получить её полные сообщения. Дополнительные параметры фильтрации: `user_id`, `application_id`, `model_group`, `model`. ### `action: update` —— Изменить заголовок или переписать историю ```json theme={null} { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", "title": "План поездки в Ханчжоу" } ``` `messages` также можно передать, но сервер будет проводить строгую проверку схемы (должен быть в форме свернутого `ToolUseContent`), несоответствие приведёт к ошибке 400. Обычно рекомендуется использовать только для изменения `title`. ### `action: delete` —— Удалить беседу ```json theme={null} { "action": "delete", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` Возвращает `{ id, success: true }`. После удаления восстановить нельзя, пожалуйста, подтвердите перед вызовом. ## Плавный переход с v1 Если вы уже используете [`/aichat/conversations`](https://platform.acedata.cloud/documents/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`), продвигаясь в своём темпе. ## Обработка ошибок Ошибки ответа унифицированы: ```json theme={null} { "error": { "code": "chat_error", "message": "upstream LLM returned an error" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` Распространённые ошибки: * `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 могут плавно перейти поэтапно. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.