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-preview、gemini-3.1-pro-preview、gemini-3.1-flash-image、gemini-3.1-pro-preview、gemini-2.5-flash-lite 等
xAI：grok-4 等
DeepSeek：deepseek-v4-pro、deepseek-v4.1-flash、deepseek-v4-flash、deepseek-v3.2-exp、deepseek-r1-0528 等
Moonshot：kimi-k3、kimi-k2.6、kimi-k2.5 等
Zhipu：glm-5.3、glm-5.2、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-preview 等）。
NDJSON 串流的欄位保持向後相容：每個 text_delta 事件仍帶有 delta_answer 與 id，因此原本按行解析 delta_answer 的用戶端無需修改。

遷移後可依需求啟用 v2 的新功能（多模態 message、SSE、工具呼叫、action CRUD），依照節奏推進即可。

錯誤處理

錯誤回應統一為：

{
  "error": {
    "code": "chat_error",
    "message": "model service 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 音頻

網絡與數據

驗證碼

身份

代理

進階

Coding

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 平滑遷移

錯誤處理

結論