AI Chat v2 API Integration Guide

The AI Chat v2 API (/aichat2/conversations) is a next-generation conversation interface and a comprehensive upgrade of the AI Chat API. Building on v1’s simplicity and managed multi-turn conversations, it expands with:

Multimodal user input: Directly send text + image + file blocks through the structured message field, without needing to attach them indirectly through references first.
Agent-based tool calling: Includes a built-in set of tools such as web search, webpage scraping, and file reading, and can mount user-authorized MCP servers (Google Drive, Notion, Slack, GitHub, etc.). The model can autonomously call tools across multiple rounds within a single request to complete complex tasks.
Structured streaming events: Through accept: text/event-stream or application/x-ndjson, you can receive token-by-token events such as text_delta, tool_use, tool_result, thinking, citation, card, and artifact, making it easy to render each type separately on the frontend.
Interruptible / resumable: When the model needs the user to provide additional information, it emits an ask_user_question event and pauses. On the next call, simply fill in the answer through tool_results to continue.
New CRUD actions: Complete retrieve / retrieve_batch / update / delete through the action field on the same endpoint, without needing an additional conversation management API.
Continuously updated model list: By default, supports modern models such as GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, and Kimi K3.

At the request body level, it is also fully backward compatible with v1: simply send model + question (+ optional stateful / id / references / preset) to receive a {answer, id} JSON response equivalent to v1. Therefore, migrating from /aichat/conversations does not require rewriting the client; you only need to change the path to /aichat2/conversations.

If you are currently using /aichat/conversations, the legacy interface will remain available, and you can migrate at your own pace.

Application Process

To use the AI Chat v2 API, first obtain your API Token from the Ace Data Cloud Console and keep it for later use.

If you have not logged in or registered yet, you will be automatically redirected to the login page to register and log in. Once completed, you will automatically return to the current page. One API Token can call all platform services; there is no need to apply separately for each service. Your first application includes free credits for a free trial; when credits are insufficient, you can top up your general balance in the Console.

📘 Full documentation: AI Chat v2 API →

Basic Usage

The simplest usage is exactly the same as v1: send model + question and receive {answer, id}. CURL example:

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。"
  }'

Response:

{
  "answer": "AceDataCloud 是一个聚合主流 AI 模型与多模态服务的统一 API 平台，开发者通过一个密钥即可调用 GPT、Claude、Gemini、Midjourney、Suno、Veo 等多家服务。",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

Python example:

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())

Available model values can be directly viewed in the dropdown of the Try panel on the right. Common categories include:

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, etc.
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, etc.
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, etc.
xAI: grok-4, etc.
DeepSeek: deepseek-v4-pro, deepseek-v4.1-flash, deepseek-v4-flash, deepseek-v3.2-exp, deepseek-r1-0528, etc.
Moonshot: kimi-k3.1-pro, kimi-k3, kimi-k2.6, kimi-k2.5, etc.
Zhipu: glm-5.3, glm-5.2, glm-5.1, glm-5, glm-5-turbo, glm-4.7, glm-4.5v, etc.

For specific billing rules, see the Pricing card on the service page.

Multi-turn Conversations

Just like v1, send stateful: true to enable conversation persistence. The API will return an id; include the id in subsequent requests to continue the conversation without maintaining the messages history yourself. First request:

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。"
  }'

Response:

{
  "answer": "好的，我已经记住了 42。需要我用它做什么吗？",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

Second request, include the same id:

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": "我刚才让你记住的数字是多少？"
  }'

{
  "answer": "你让我记住的数字是 42。",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

stateful defaults to true; omitting it is equivalent to explicitly passing true. If you do not want the server to save this round of conversation, you can explicitly set stateful: false.

Streaming Responses

v2 supports two streaming formats, selected according to the accept header:

Scenario	`accept`	Data Format
Web frontend / EventSource	`text/event-stream`	`data: {json}\n\n`, with the final line as `data: [DONE]\n\n`
Server-side / CLI / Node streaming parsing	`application/x-ndjson`	One JSON object per line
Streaming not required	`application/json` (default)	Returns `{answer, id}` in one response

NDJSON Example

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"))

Each line of NDJSON is a structured event, the most common of which is text_delta:

{"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 Example

Using EventSource in the browser does not support custom request bodies. It is recommended to use fetch + manually parse slices by \n\n:

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);
  }
}

Streaming Event Types

`type`	Meaning
`text_delta`	An incremental text fragment of the assistant’s answer. `content` contains the newly added content; for v1 compatibility, the same event also carries `delta_answer` (equal to `content`) and `id`.
`thinking`	The model’s reasoning process (only appears when the selected model exposes reasoning).
`tool_use`	The model decides to call a tool; the event carries `tool_id`, `tool_name`, and `input`.
`tool_result`	The tool execution result, paired with the preceding `tool_use` through `tool_id`; `is_error` indicates whether it failed.
`card`	A structured card generated by a tool (such as an image or link preview), suitable for direct rendering.
`citation`	A source URL used to supplement citations for the corresponding text fragment.
`ask_user_question`	Emitted when the model needs the user to provide additional information. The conversation enters the `awaiting_user_input` state; see Resuming a Paused Conversation below.
`artifact`	An independent artifact generated by the model (such as a code block or document), which can be saved or downloaded.
`system_message`	A system prompt message (not user or assistant content), used only for UI prompts.
`compact`	An event indicating that the internal context has been compressed; no special handling is required.
`error`	An error occurred in this round; `message` describes the error.
`done`	The streaming response has ended, carrying `usage` (including `prompt_tokens` / `completion_tokens` / `total_tokens`) and `terminal_reason`.

For clients that only care about the final answer, concatenating the content of all text_delta events is equivalent to answer in application/json mode.

Multimodal Input

If the user input contains images or files, pass message (an array) instead of question. Each array element is a content block:

{
  "model": "gpt-5.4",
  "stateful": true,
  "message": [
    { "type": "text", "text": "这张图片里有几只猫？" },
    { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } }
  ]
}

Supported block types:

text — Plain text; the text field is required.
image_url — An image; image_url.url is required.
file_url — A file (PDF, CSV, TXT, etc.); file_url.url is required.

Relationship with v1 `references`

For compatibility with older clients, v2 still recognizes the references: ["https://...", ...] field:

URLs with the suffix jpg / jpeg / png / gif / bmp / webp / svg / heic / heif are automatically converted into image_url blocks;
Other extensions are converted into file_url blocks;
If question is also provided, it is prepended as a text block.

Therefore, if you only want to migrate from v1 and do not want to modify the request body, simply change the path to /aichat2/conversations; the original references usage will continue to work as usual. For finer control (for example, placing multiple images between text, or when ordering is important), use the message array directly.

Tool Calls and MCP

The core enhancement of v2 is that the model can autonomously call tools to complete multi-step tasks. This is enabled by default, and the client does not need to make any additional configuration in the request. Common scenarios:

The user asks, “Help me search for recent new exhibitions in Shanghai” → the model calls the built-in web search → organizes the results into an answer.
The user asks, “Read this PDF and then write a summary” → the model calls file_read → writes a summary.
The user has authorized Google Drive / GitHub / Notion, etc. in Connections → the model can call the corresponding MCP tools to read and write their data.

In the NDJSON / SSE stream, tool calls are represented through the two types of events tool_use and tool_result, for example:

{"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-..."}
...

If you do not want to display tool call details on the frontend, simply ignore event types such as tool_use / tool_result / card / citation; the model’s final output will still stream through text_delta. max_turns can limit the maximum number of rounds in which the model can call tools on its own within this request. The range is 1–500, and the default is 500 when omitted. Setting it low (for example, max_turns: 1) can force a single response and disallow any tool calls.

Asynchronous Execution and Unattended Authorization

If your calls come from alert Webhooks, CI/CD, monitoring systems, or other background tasks, you can set async: true to have the API immediately return a task ID while execution continues in the background:

{
  "model": "gpt-5.5",
  "async": true,
  "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……"
}

Example response:

{
  "task_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "conversation_id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "status": "queued"
}

Afterward, you can use action: retrieve + id to query the conversation result; you can also provide callback_url, and when the task is completed, the platform will POST { status, answer, usage, error } to your callback address. callback_url must use http / https, and you cannot directly specify localhost or a private IP literal address. There is usually no one available to click confirmation for background tasks. If you want certain Skills or MCP Servers to perform actions such as sending, publishing, or writing in unattended mode, explicitly pass a pre-authorization list in the request body:

{
  "model": "gpt-5.5",
  "async": true,
  "allowed_skills": ["acedatacloud/personal-wechat"],
  "allowed_mcp_servers": [],
  "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……"
}

Values in allowed_skills are the slugs of connected Skills; values in allowed_mcp_servers are the slugs of connected MCP Servers. Skills / MCP Servers not included in the pre-authorization list can still only preview, dry-run, or refuse to perform write operations in unattended mode. If more granular control is needed, you can also use the equivalent unattended_policy object:

{
  "unattended_policy": {
    "allowed_skills": ["acedatacloud/personal-wechat"],
    "allowed_mcp_servers": [],
    "expires_at": 1790000000
  }
}

Pre-authorization consists of these two lists themselves: an empty list means no capabilities are authorized, with no additional switch field required. Note: Pre-authorization only means that “this request allows these capabilities to skip manual confirmation in unattended mode.” The specific Skill must still support --unattended-confirm or a corresponding security mechanism; otherwise, it will continue to dry-run and will not directly perform write operations.

Resuming Paused Conversations

Some tools cause the model to “ask the user a follow-up question.” At this point, the model emits an ask_user_question event, and the conversation is frozen in the awaiting_user_input state:

{
  "type": "ask_user_question",
  "tool_id": "toolu_01XYZW",
  "tool_name": "ask_user_question",
  "question": "你希望生成的报告是中文还是英文？",
  "options": ["中文", "英文"],
  "id": "f2f4b3e8-..."
}

Render this event as a card on the frontend for the user to choose an answer, then initiate the next request using the same id and fill the answer back through tool_results:

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": "中文"
      }
    ]
  }'

The tool_use_id in the request body must exactly match the tool_id from when the conversation was paused; otherwise, a 400 error will be returned. When tool_results is present in the request, question / message / references will all be ignored. If the user decides to abandon this question, simply pass a new question / message; the platform will automatically mark the paused tool call as “skipped by user.”

Conversation Management (CRUD)

v2 provides lightweight conversation management through the action field on the same endpoint, without requiring a separate API.

`action: retrieve` —— Retrieve a conversation

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"
  }'

Returns the complete conversation document (including messages history, model, title, tools_used, etc.).

`action: retrieve_batch` —— List conversation summaries

{
  "action": "retrieve_batch",
  "model_group": "chatgpt",
  "limit": 20,
  "offset": 0
}

Returns { items: [...], total }. Summaries do not include messages, making them suitable for sidebar lists; if the user opens a conversation, use action: retrieve to retrieve its complete messages separately. Optional filter parameters: user_id, application_id, model_group, model.

`action: update` —— Change the title or rewrite the history

{
  "action": "update",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "title": "Hangzhou Travel Plan"
}

You can also pass messages, but the server performs strict schema validation (it must be in the collapsed ToolUseContent format), and returns 400 if it does not comply. Generally, it is only recommended for changing the title.

`action: delete` —— Delete a conversation

{
  "action": "delete",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

Returns { id, success: true }. Deleted conversations cannot be recovered, so please confirm before calling.

Smooth migration from v1

If you are already using /aichat/conversations, migrating to v2 requires almost no code changes:

Change the URL from https://api.acedata.cloud/aichat/conversations to https://api.acedata.cloud/aichat2/conversations.
If you previously passed v1 model names (such as gpt-3.5, gpt-4-browsing, etc.), it is recommended to upgrade to current-generation models when switching to v2 (such as gpt-5.4, claude-opus-4-8, gemini-3.1-pro-preview, etc.).
NDJSON stream fields remain backward compatible: every text_delta event still includes delta_answer and id, so clients that originally parse delta_answer line by line require no changes.

After migration, you can enable v2’s new capabilities as needed (multimodal message, SSE, tool calling, action CRUD) and proceed at your own pace.

Error handling

Error responses are uniformly formatted as:

{
  "error": {
    "code": "chat_error",
    "message": "model service returned an error"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Common errors:

400 bad_request: Missing required fields, mismatched tool_use_id, invalid messages schema, etc.
401 invalid_token: The authorization header is incorrect.
404 not_found: The conversation corresponding to the id does not exist when using action: retrieve / update / delete.
429 too_many_requests: The rate limit has been triggered.
500 chat_error: An upstream LLM error occurred, or completion_tokens=0 in the current round (treated as unconsumed and will not be charged).

In streaming responses, errors are emitted as {"type":"error","message":"..."} events, followed immediately by the end of the stream.

Conclusion

While remaining backward compatible with v1, the AI Chat v2 API upgrades conversations from “single-turn / multi-turn Q&A” to “agentic observable conversations”: multimodal input, tool calling, pausable / resumable interactions, structured streaming events, and built-in CRUD. It is recommended that new integrations use v2 directly; existing v1 integrations can migrate smoothly in stages. If you have any questions, please contact our technical support team at any time.

Getting Started

Core Concepts

Integrations

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Coding

More guides

AI Chat v2 API Integration Guide

Application Process

Basic Usage

Multi-turn Conversations

Streaming Responses

NDJSON Example

SSE Example

Streaming Event Types

Multimodal Input

Relationship with v1 `references`

Tool Calls and MCP

Asynchronous Execution and Unattended Authorization

Resuming Paused Conversations

Conversation Management (CRUD)

`action: retrieve` —— Retrieve a conversation

`action: retrieve_batch` —— List conversation summaries

`action: update` —— Change the title or rewrite the history

`action: delete` —— Delete a conversation

Smooth migration from v1

Error handling

Conclusion

​Application Process

​Basic Usage

​Multi-turn Conversations

​Streaming Responses

​NDJSON Example

​SSE Example

​Streaming Event Types

​Multimodal Input

​Relationship with v1 references

​Tool Calls and MCP

​Asynchronous Execution and Unattended Authorization

​Resuming Paused Conversations

​Conversation Management (CRUD)

​action: retrieve —— Retrieve a conversation

​action: retrieve_batch —— List conversation summaries

​action: update —— Change the title or rewrite the history

​action: delete —— Delete a conversation

​Smooth migration from v1

​Error handling

​Conclusion

Application Process

Basic Usage

Multi-turn Conversations

Streaming Responses

NDJSON Example

SSE Example

Streaming Event Types

Multimodal Input

Relationship with v1 `references`

Tool Calls and MCP

Asynchronous Execution and Unattended Authorization

Resuming Paused Conversations

Conversation Management (CRUD)

`action: retrieve` —— Retrieve a conversation

`action: retrieve_batch` —— List conversation summaries

`action: update` —— Change the title or rewrite the history

`action: delete` —— Delete a conversation

Smooth migration from v1

Error handling

Conclusion