AI Chat v2 API 對接說明

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 可拿到逐 token 的 text_delta、tool_use、tool_result、thinking、citation、card、artifact 等事件，便於在前端按對應類型分別渲染。
可中斷 / 可恢復：模型在需要用戶補充信息時會發出 ask_user_question 事件並暫停，下次調用通過 tool_results 回填答案即可繼續。
新增 CRUD 動作：在同一個 endpoint 上通過 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）即可得到與 v1 等價的 {answer, id} JSON 回應，所以從 /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 示例：

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

返回結果：

{
  "answer": "AceDataCloud 是一個聚合主流 AI 模型與多模態服務的統一 API 平台，開發者通過一個密鑰即可調用 GPT、Claude、Gemini、Midjourney、Suno、Veo 等多家服務。",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}

Python 示例：

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 帶回來即可繼續對話，無需自己維護 messages 歷史。第一次請求：

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

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

第二次請求，帶上同一個 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 默认为 true，省略和显式传 true 等价。如果你不希望服务端保存这一轮对话，可以显式设置 stateful: false。

流式响应

v2 支持两种流式格式，按照 accept 头选择：

场景	`accept`	数据形态
Web 前端 / EventSource	`text/event-stream`	`data: {json}\n\n`，最后一行 `data: [DONE]\n\n`
服务端 / CLI / Node 流式解析	`application/x-ndjson`	每行一个 JSON 对象
不需要流式	`application/json`（默认）	一次性返回 `{answer, id}`

NDJSON 示例

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：

{"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 切片解析：

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 拼接起来就和 application/json 模式下的 answer 等价。

多模态输入

如果用户输入包含图片或文件，传 message（数组）代替 question。每个数组元素是一个内容块：

{
  "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 的核心增強點是模型可以自主調用工具完成多步任務，這是默認開啟的，不需要客戶端在請求裡做任何額外配置。常見場景：

用戶問「幫我搜一下最近上海有什麼新展覽」→ 模型調用內置 web search → 把結果整理成回答。
用戶問「讀一下這個 PDF 然後寫個摘要」→ 模型調用 file_read → 寫摘要。
用戶已在 Connections 裡授權了 Google Drive / GitHub / Notion 等 → 模型可調用對應的 MCP 工具讀寫其數據。

在 NDJSON / SSE 流裡，工具調用通過 tool_use 和 tool_result 兩類事件呈現，例如：

{"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）可以強制單次回答、不允許任何工具調用。

非同步執行與無人值守授權

如果你的調用來自告警 Webhook、CI/CD、監控系統或其他後台任務，可以設置 async: true 讓接口立即返回任務 ID，後台繼續執行：

{
  "model": "gpt-5.5",
  "async": true,
  "question": "我的服務報警了，用個人微信通知微信群「AceDataCloud團隊」……"
}

返回示例：

{
  "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 } POST 到你的回調地址。callback_url 必須使用 http / https，且不能直接填寫 localhost 或私有 IP 字面地址。後台任務通常沒有人能點擊確認。如果你希望某些 Skill 或 MCP Server 在無人值守模式下執行發送、發布、寫入等動作，請在請求體裡顯式傳預授權列表：

{
  "model": "gpt-5.5",
  "async": true,
  "allowed_skills": ["acedatacloud/personal-wechat"],
  "allowed_mcp_servers": [],
  "question": "我的服務報警了，用個人微信通知微信群「AceDataCloud團隊」……"
}

allowed_skills 裡的值是已連接 Skill 的 slug；allowed_mcp_servers 裡的值是已連接 MCP Server 的 slug。未列入預授權的 Skill / MCP Server 在無人值守模式下仍只能預覽、dry-run 或拒絕執行寫操作。如果需要更細的控制，也可以使用等價的 unattended_policy 對象：

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

預授權就是這兩個列表本身：列表為空即不授權任何能力，無需額外的開關字段。注意：預授權只代表「本次請求允許這些能力在無人值守模式下跳過人工確認」。具體 Skill 仍必須支持 --unattended-confirm 或對應的安全機制；否則它會繼續 dry-run，不會直接執行寫操作。

恢復暫停的對話

某些工具會讓模型「反問用戶」，模型這時會發出一個 ask_user_question 事件，對話被凍結在 awaiting_user_input 狀態：

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

在前端把這個事件渲染成卡片讓用戶選答案，然後用同一個 id 發起下一次請求，把答案通過 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": "中文"
      }
    ]
  }'

請求體中 tool_use_id 必須和暫停時的 tool_id 完全一致；不一致會返回 400。當請求裡同時存在 tool_results 時，question / message / references 都會被忽略。如果用戶決定放棄這個問題，直接傳一個新的 question / message 即可，平台會自動把暫停的工具調用標記為「用戶跳過」。

會話管理（CRUD）

v2 在同一個 endpoint 上通過 action 字段提供輕量級會話管理，無需另外開 API。

`action: retrieve` —— 拉取一個會話

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` —— 列出會話摘要

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

返回 { items: [...], total }。摘要不包含 messages，適合做側邊欄列表；如果用戶點開某條會話，再用 action: retrieve 單獨拉取它的完整消息。可選過濾參數：user_id、application_id、model_group、model。

`action: update` —— 改標題或重寫歷史

{
  "action": "update",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "title": "杭州旅行計劃"
}

messages 也可以傳，但服務端會做嚴格的 schema 校驗（必須是折疊後的 ToolUseContent 形態），不符合會返回 400。一般只建議用來改 title。

`action: delete` —— 刪除一個會話

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

返回 { id, success: true }。刪除後無法恢復，請確認後再調用。

從 v1 平滑遷移

如果你已經在使用 /aichat/conversations，遷移到 v2 幾乎不需要改碼：

把 URL 由 https://api.acedata.cloud/aichat/conversations 改成 https://api.acedata.cloud/aichat2/conversations。
如果你之前傳的是 v1 模型名（如 gpt-3.5、gpt-4-browsing 等），切換到 v2 時建議升級到當代模型（如 gpt-5.4、claude-opus-4-8、gemini-3.1-pro 等）。
NDJSON 流的字段保持向後兼容：每個 text_delta 事件依然帶 delta_answer 與 id，因此原來按行解析 delta_answer 的客戶端無需改動。

遷移之後可以按需啟用 v2 的新能力（多模態 message、SSE、工具調用、action CRUD），按節奏推進即可。

錯誤處理

錯誤響應統一為：

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

常見錯誤：

400 bad_request：缺少必填字段、tool_use_id 不匹配、messages schema 非法等。
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":"..."} 事件發出，緊接著流就會結束。

結論

AI Chat v2 API 在向後兼容 v1 的同時，把對話從「單輪 / 多輪問答」升級為「Agent 化的可觀測對話」：多模態輸入、工具調用、可暫停 / 可恢復、流式結構化事件、內建 CRUD。建議新接入直接使用 v2；已有 v1 集成可以分階段平滑遷移。如有任何問題，請隨時聯繫我們的技術支持團隊。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

代理

進階

AI Chat v2 API 對接說明

申請流程

基本使用

多輪對話

流式响应

NDJSON 示例

SSE 示例

流式事件类型

多模态输入

与 v1 `references` 的关系

工具調用與 MCP

非同步執行與無人值守授權

恢復暫停的對話

會話管理（CRUD）

`action: retrieve` —— 拉取一個會話

`action: retrieve_batch` —— 列出會話摘要

`action: update` —— 改標題或重寫歷史

`action: delete` —— 刪除一個會話

從 v1 平滑遷移

錯誤處理

結論

​申請流程

​基本使用

​多輪對話

​流式响应

​NDJSON 示例

​SSE 示例

​流式事件类型

​多模态输入

​与 v1 references 的关系

​工具調用與 MCP

​非同步執行與無人值守授權

​恢復暫停的對話

​會話管理（CRUD）

​action: retrieve —— 拉取一個會話

​action: retrieve_batch —— 列出會話摘要

​action: update —— 改標題或重寫歷史

​action: delete —— 刪除一個會話

​從 v1 平滑遷移

​錯誤處理

​結論

申請流程

基本使用

多輪對話

流式响应

NDJSON 示例

SSE 示例

流式事件类型

多模态输入

与 v1 `references` 的关系

工具調用與 MCP

非同步執行與無人值守授權

恢復暫停的對話

會話管理（CRUD）

`action: retrieve` —— 拉取一個會話

`action: retrieve_batch` —— 列出會話摘要

`action: update` —— 改標題或重寫歷史

`action: delete` —— 刪除一個會話

從 v1 平滑遷移

錯誤處理

結論