> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Chat v2 API 对接说明

> AI Dialogue 集成指南 - XHuoAPI

AI Chat v2 API（`/aichat2/conversations`）是新一代的对话接口，是 [AI Chat API](https://api.xhuoapi.ai/documents/59fb1199-6694-4afb-a222-3554d7f7d05a) 的全面升级版本。它在 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.7、Claude Sonnet 4.6、Gemini 3.1 Pro、GLM 5.1、DeepSeek V4、Kimi K2.5 等当代模型。

同时它在请求体层面**完全向后兼容 v1**：只传 `model` + `question`（+ 可选 `stateful` / `id` / `references` / `preset`）即可得到与 v1 等价的 `{answer, id}` JSON 响应，所以从 `/aichat/conversations` 迁移过来不需要重写客户端，只需把路径换为 `/aichat2/conversations`。

> 如果你目前在使用 `/aichat/conversations`，旧接口仍会保留服务，可以按自己的节奏迁移。

## 申请流程

要使用 API，需要先到 [AI Chat v2 API](https://api.xhuoapi.ai/documents/e4a7c2b9-3f1d-4e8a-9b6c-a5d2f8e1b4c7) 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮即可获取请求所需要的凭证。

如果你尚未登录或注册，会自动跳转到登录页面，注册并登录之后会自动返回当前页面。

在首次申请时会有免费额度赠送，可以免费使用该 API。

## 基本使用

最简单的用法和 v1 完全一致：传 `model` + `question`，拿到 `{answer, id}`。

CURL 示例：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.4",
    "question": "用一句话介绍下 XHuoAPI。"
  }'
```

返回结果：

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

Python 示例：

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/aichat2/conversations"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "model": "gpt-5.4",
    "question": "用一句话介绍下 XHuoAPI。",
}

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-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`、`grok-4-1-fast`、`grok-4-1-fast-reasoning`、`grok-3-mini-fast` 等
* DeepSeek：`deepseek-v4-flash`、`deepseek-v3.2-exp`、`deepseek-r1-0528` 等
* Moonshot：`kimi-k2.5`、`kimi-k2-thinking`、`kimi-k2-thinking-turbo` 等
* Zhipu：`glm-5.1`、`glm-5`、`glm-5-turbo`、`glm-4.7`、`glm-4.5v` 等

具体计费规则参见服务页面的 Pricing 卡片。

## 多轮对话

和 v1 一样，传 `stateful: true` 开启会话保存，API 会返回一个 `id`；后续请求把 `id` 带回来即可继续对话，无需自己维护 messages 历史。

第一次请求：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.4",
    "stateful": true,
    "question": "记住一个数字：42。"
  }'
```

返回：

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

第二次请求，带上同一个 `id`：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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": "我刚才让你记住的数字是多少？"
  }'
```

```json theme={null}
{
  "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 示例

```python theme={null}
import json
import requests

url = "https://api.xhuoapi.ai/v1/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`：

```json theme={null}
{"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` 切片解析：

```javascript theme={null}
const resp = await fetch("https://api.xhuoapi.ai/v1/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`。每个数组元素是一个内容块：

```json theme={null}
{
  "model": "gpt-5.4",
  "stateful": true,
  "message": [
    { "type": "text", "text": "这张图片里有几只猫？" },
    { "type": "image_url", "image_url": { "url": "https://cdn.xhuoapi.ai/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](https://api.xhuoapi.ai/connections) 里授权了 Google Drive / GitHub / Notion 等 → 模型可调用对应的 MCP 工具读写其数据。

在 NDJSON / SSE 流里，工具调用通过 `tool_use` 和 `tool_result` 两类事件呈现，例如：

```json theme={null}
{"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`）可以强制单次回答、不允许任何工具调用。

## 恢复暂停的对话

某些工具会让模型「反问用户」，模型这时会发出一个 `ask_user_question` 事件，对话被冻结在 `awaiting_user_input` 状态：

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

在前端把这个事件渲染成卡片让用户选答案，然后用同一个 `id` 发起下一次请求，把答案通过 `tool_results` 回填：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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` —— 拉取一个会话

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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` —— 列出会话摘要

```json theme={null}
{
  "action": "retrieve_batch",
  "model_group": "chatgpt",
  "limit": 20,
  "offset": 0
}
```

返回 `{ items: [...], total }`。**摘要不包含 `messages`**，适合做侧边栏列表；如果用户点开某条会话，再用 `action: retrieve` 单独拉取它的完整消息。

可选过滤参数：`user_id`、`application_id`、`model_group`、`model`。

### `action: update` —— 改标题或重写历史

```json theme={null}
{
  "action": "update",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44",
  "title": "杭州旅行计划"
}
```

`messages` 也可以传，但服务端会做严格的 schema 校验（必须是折叠后的 `ToolUseContent` 形态），不符合会返回 400。一般只建议用来改 `title`。

### `action: delete` —— 删除一个会话

```json theme={null}
{
  "action": "delete",
  "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44"
}
```

返回 `{ id, success: true }`。删除后无法恢复，请确认后再调用。

## 从 v1 平滑迁移

如果你已经在使用 [`/aichat/conversations`](https://api.xhuoapi.ai/documents/59fb1199-6694-4afb-a222-3554d7f7d05a)，迁移到 v2 几乎不需要改代码：

1. 把 URL 由 `https://api.xhuoapi.ai/v1/aichat/conversations` 改成 `https://api.xhuoapi.ai/v1/aichat2/conversations`。
2. 如果你之前传的是 v1 模型名（如 `gpt-3.5`、`gpt-4-browsing` 等），切换到 v2 时建议升级到当代模型（如 `gpt-5.4`、`claude-opus-4-7`、`gemini-3.1-pro` 等）。
3. NDJSON 流的字段保持向后兼容：每个 `text_delta` 事件依然带 `delta_answer` 与 `id`，因此原来按行解析 `delta_answer` 的客户端无需改动。

迁移之后可以按需启用 v2 的新能力（多模态 `message`、SSE、工具调用、`action` CRUD），按节奏推进即可。

## 错误处理

错误响应统一为：

```json theme={null}
{
  "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 集成可以分阶段平滑迁移。如有任何问题，请随时联系我们的技术支持团队。