How to Build a Stateful, Streaming AI Chat Endpoint with Ace Data Cloud

How to Build a Stateful, Streaming AI Chat Endpoint with Ace Data Cloud

When you are building an assistant into a product, the hard part is rarely the first prompt. The hard part is keeping useful context, streaming partial output to the UI, accepting images or files, and giving the model enough room to call tools without turning your backend into a pile of one-off integrations.

The Ace Data Cloud AI Chat v2 API is designed for that middle layer: a single conversation endpoint that can behave like a simple chat API, but also supports stateful conversations, structured streaming events, multimodal input, tool-use events, async tasks, and conversation management actions. This guide walks through the practical integration path using only the fields and behavior documented for /aichat2/conversations.

What you can do

At its simplest, AI Chat v2 accepts a model and a question, then returns a JSON object with answer and id. That makes it easy to migrate from a basic chat flow without changing your entire client.

  • Stateful conversations by passing stateful: true and reusing the returned id.
  • Streaming output with accept: text/event-stream for SSE-style events or accept: application/x-ndjson for one JSON event per line.
  • Multimodal input with a structured message array containing text, image_url, or file_url blocks.
  • Tool-aware UX by rendering or ignoring events such as tool_use, tool_result, citation, card, and artifact.
  • Background execution by passing async: true and later retrieving the result by id, or receiving a callback at callback_url.

How it works

The endpoint is:

POST https://api.acedata.cloud/aichat2/conversations

Use your Ace Data Cloud API token in the authorization header:

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": "Summarize this API in one sentence."
  }'

The JSON response shape is intentionally small:

{
  "answer": "...",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

That returned id is the handle you use when you want the server to continue a stored conversation instead of sending the whole message history again.

Start with the boring path first

Before adding streaming or tools, make one normal JSON call. This keeps debugging simple: if the request fails, the problem is likely authentication, model selection, headers, or JSON structure. The minimum payload is just model plus question.

The documentation notes that stateful defaults to true. If you do not want Ace Data Cloud to save the turn, explicitly pass stateful: false. For product assistants, I usually keep the first implementation stateful and store the returned id in my own session table.

Continue a conversation without replaying messages

For multi-turn use, send the next request with the same id. You can keep the request body compact:

{
  "model": "gpt-5.4",
  "stateful": true,
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "question": "What did I ask you to remember?"
}

This is useful when your frontend is stateless, when several workers may handle the same user over time, or when you simply do not want to keep reconstructing a long message array on every request.

Stream events your UI can understand

When you use accept: application/x-ndjson, each response line is a JSON event. A minimal Python client can concatenate text_delta events and inspect the final done event for usage:

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": "Introduce Hangzhou in three sentences.",
}

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":
            answer += event["content"]
            print(event["delta_answer"], end="", flush=True)
        elif event.get("type") == "done":
            print("\nusage =", event.get("usage"))

The same endpoint can emit other event types, including thinking, tool_use, tool_result, card, citation, ask_user_question, artifact, system_message, compact, error, and done. If your app only needs final text, ignore the extra events and concatenate content from text_delta.

Add images or files when the prompt needs them

For multimodal input, use message instead of question. The order of blocks is preserved, which is helpful when text refers to a specific image or file:

{
  "model": "gpt-5.4",
  "stateful": true,
  "message": [
    { "type": "text", "text": "How many cats are in this image?" },
    { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } }
  ]
}

The supported block types are text with required text, image_url with required image_url.url, and file_url with required file_url.url. Older clients can still use references; image extensions such as jpg, jpeg, png, gif, bmp, webp, svg, heic, and heif are converted into image blocks, while other extensions become file blocks.

Use async mode for background work

If a request comes from a webhook, CI job, or monitoring system, pass async: true. The API immediately returns a task-style payload containing fields such as task_id, conversation_id, id, and status. Later, query the result with action: retrieve and id, or provide a callback_url. The callback URL must use http or https and cannot directly target localhost or a private IP literal address.

Where to go next

The clean path is: first make a JSON request, then add stateful continuation, then switch your UI to NDJSON or SSE streaming, and only after that render advanced events such as tool calls, cards, citations, and artifacts. That sequence gives you a working assistant early, while leaving room for richer workflows later.

For the full field list, streaming event definitions, resume flow, and async details, read the AI Chat v2 API documentation.

Comments

Popular posts from this blog

Artistic QR Code API Integration Guidance

How to Configure Claude Code with CC Switch and Ace Data Cloud

How to Build a Server-Side Image Editing Workflow with GPT-Image-2