Article Description: AI Chat v2 retains the simple calling method of the original conversation API, while adding multimodal input, structured event streams, automatic tool calling, pause and resume, asynchronous execution, and conversation management. This article starts with a migration that requires almost no code rewriting and explains how these changes affect real product development.
Many chat APIs work well during the demo stage: pass in a question, wait for the model to return a piece of text, and then display the text on the page.
As the product continues to move forward, things are no longer just “ask one question, answer one question.” Users will upload PDFs and screenshots, and the model needs to search the web, read files, and even call authorized tools such as GitHub and Notion. A task may last for several rounds, and may pause midway to ask follow-up questions because information is missing. At this point, if the API still returns only a continuously growing string of text, it is difficult for the frontend to know what the model is doing, and the backend also has difficulty determining whether the task has actually finished.
Ace Data Cloud AI Chat v2 API solves exactly this problem. It does not overturn the original conversation method, but on the basis of compatibility with simple calls, it breaks a response into events that programs can recognize and process: text is text, tool calls are tool calls, and citations, files, errors, and final status each have a clear place.

Image: AI Chat v2 no longer compresses the entire task into a piece of text, but keeps input, tools, and output events structured.
¶ Migration can start by changing just one URL
If the project is using the old /aichat/conversations, there is no need to rewrite the message structure first, nor is there a need to build an Agent interface first. V2 continues to accept fields such as the original model, question, stateful, id, references, and preset. The minimal migration only requires changing the request URL to:
https://api.acedata.cloud/aichat2/conversations
A most basic request is still very short:
curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
-H 'accept: application/json' \
-H 'authorization: Bearer YOUR_API_TOKEN' \
-H 'content-type: application/json' \
-d '{
"model": "YOUR_SUPPORTED_MODEL",
"question": "Please summarize the three most important issues in these requirements.",
"stateful": true
}'
In normal JSON mode, the API still returns familiar results:
{
"answer": "...",
"id": "conversation-uuid"
}
Save the returned id, and include the same id in the next request to continue the conversation. stateful defaults to true, and is used to control whether to load and continue the context of a saved conversation.
This step is very suitable for real projects: first verify whether authentication, models, latency, and old business logic work properly, and then gradually integrate new capabilities. Migration does not have to be tied to interface refactoring in the same release.
¶ When files and images enter the conversation, order also becomes information
The old question is suitable for pure text. For tasks such as “first read the report, then compare it with the screenshot, and finally give a conclusion,” a simple attachment list is no longer precise enough. V2 adds a structured message array, which can place text, images, and files in order:
{
"model": "YOUR_SUPPORTED_MODEL",
"stateful": true,
"message": [
{
"type": "text",
"text": "Read the report, and compare the trends in it with the dashboard screenshot that follows."
},
{
"type": "file_url",
"file_url": {"url": "https://example.com/report.pdf"}
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/dashboard.png"}
}
]
}
Available content blocks include text, image_url, and file_url. What matters is not only “supporting attachments,” but that the relationships between content are not lost during transmission. The client can clearly tell the model: which part is the task instruction, which document is the original material, and what should be compared next.
To allow old clients to migrate smoothly, V2 still recognizes references. URLs with image file extensions are processed as images, and other URLs are processed as files. If you are only upgrading the API, you can temporarily keep the original format; if the input order affects understanding, it is recommended to use message.
¶ Streaming responses are no longer only “typing”
Traditional streaming output usually contains only text increments. After the model starts searching, reading files, or calling external tools, the page appears to be stuck, users do not know whether the task is continuing, and developers also cannot obtain clear status.
AI Chat v2 provides three response methods through the accept request header:
| Use Case | accept |
Return Method |
|---|---|---|
| Simple server-side requests | application/json |
Returns {answer, id} after completion |
| Node, Python, CLI, or Worker | application/x-ndjson |
One JSON event per line |
| Web frontend | text/event-stream |
SSE event stream |
In NDJSON and SSE modes, the response is not just tokens, but a set of typed events. text_delta is used for text increments, tool_use indicates that the model is preparing to call a tool, tool_result returns tool results, citation provides citation sources, card and artifact carry cards or artifacts that can be displayed separately, error indicates that this round has failed, and done provides usage and termination reasons.
The Python consumer below concatenates text while retaining key status:
import json
import os
import requests
url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
"accept": "application/x-ndjson",
"authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
"content-type": "application/json",
}
payload = {
"model": os.environ["ACEDATA_CHAT_MODEL"],
"question": "Search for information and provide a brief conclusion with sources.",
"stateful": True,
}
with requests.post(url, json=payload, headers=headers,
stream=True, timeout=120) as response:
response.raise_for_status()
answer = []
for raw_line in response.iter_lines():
if not raw_line:
continue
event = json.loads(raw_line)
event_type = event.get("type")
if event_type == "text_delta":
answer.append(event.get("content", ""))
elif event_type == "tool_use":
print("Starting call:", event.get("tool_name"))
elif event_type == "tool_result":
print("Whether the tool failed:", event.get("is_error"))
elif event_type == "error":
raise RuntimeError(event.get("message", "Unknown error"))
elif event_type == "done":
print("Usage:", event.get("usage"))
print("Termination reason:", event.get("terminal_reason"))
print("".join(answer))
If the product only cares about the final text, simply concatenate all text_delta.content; if it needs to build an observable Agent interface, it can render tool calls, citations, artifacts, and states separately. Both requirements use the same interface, with no need to maintain two sets of protocols for “simple chat” and “complex tasks.”
¶ Tool calls are enabled by default, but products still need to draw clear boundaries
V2 allows the model to call built-in capabilities such as web search, page extraction, and file reading according to task requirements; after users connect and authorize the corresponding services, it can also use MCP tools to process external data from GitHub, Notion, and more.
The stream will separately contain tool_use and tool_result, which are paired through tool_id. The frontend can use this to display real progress, and the backend can also record the duration and failure location of each tool.
Tools being callable automatically does not mean the execution scope should be opened up without limits. max_turns is used to constrain the number of Agent iteration rounds in a request, and the range given in the documentation is 1–500; when set to 1, this round only performs one model call and will not continue into tool calls. Production environments should actively configure it based on task complexity, response time, and cost budget, rather than relying on a large default limit for the long term.
For Webhook, CI/CD, or monitoring tasks, V2 supports async: true, allowing tasks to run in the background and obtain results through queries or callback_url. However, actions involving sending, publishing, or writing require explicit preauthorization through allowed_skills, allowed_mcp_servers, or unattended_policy.
Connections solve “whether it can access,” while authorization policies solve “whether it can act on behalf of the user this time.” These two things cannot be mixed together.
¶ When an Agent lacks information, there is no need to pretend the task has been completed
Complex tasks often get stuck on specific questions: which channel to publish to, which format to use, or whether to overwrite existing files. V2 provides the ask_user_question event for this purpose. After the event appears, the session enters a state of waiting for user input.
The client saves the current session id and the corresponding tool_id, displays the question and collects the answer, then uses the same session id to return the response through tool_results, and the task can continue from the pause point. This mechanism is also suitable for approval nodes. Rather than allowing the model to guess on its own when materials are insufficient, it is better to return the missing choices to the user.
¶ Sessions themselves can also be managed
V2 adds lightweight session CRUD within the same endpoint, distinguishing retrieve, retrieve_batch, update, and delete through action.
retrieve_batch returns summaries without complete messages, making it suitable for a session sidebar; when users actually open a session, call retrieve again to read the full content. For long sessions, server-side context consolidation will not use summaries to overwrite saved original messages. When continuing to revise an article, verify numbers, or prepare for publishing, the original text should still be read rather than using summaries as a replacement for the full content.
¶ Before launch, do not only verify “whether any text is returned”
After integrating an Agent API, receiving partial text does not mean that the current round has been reliably completed; the end of a stream does not necessarily mean the task succeeded. Clients should handle error and record usage and terminal_reason after receiving done. In SSE, [DONE] only indicates that transmission has ended and cannot override error events that have already appeared.
API Tokens should only be stored on the server side; stream parsers must be able to handle network chunks and temporarily unrecognized new events; tool calls should be paired by tool_id; citation links and artifacts must be rendered safely; writable connections should continue to retain human confirmation or sufficiently narrow unattended authorization. Model names, billing, and available capabilities may be updated, so formal integrations should follow the current documentation, service pages, and console, rather than hard-coding example configurations for the long term.
The most noteworthy aspect of AI Chat v2 is not adding a few more buttons to the chat window. It finally allows applications to see what happens inside an AI task: when the model outputs text, when it calls tools, where it waits for users, and in what state it ends.
If existing projects are still just ordinary Q&A boxes, they can first change the interface address and continue using the original request body. Once this step is stable, they can then integrate message, NDJSON or SSE, tool timelines, and pause-and-resume. The upgrade can be small, but it leaves enough space for future product forms.
