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

# 迁移现有集成

> 改两个常量，然后阅读行为不同的几处。

本 API 实现了标准异步任务协议。对于它支持的端点，请求和响应结构保持不变，因此能正常工作的客户端通常无需修改代码。

## 迁移方法

```diff theme={null}
- const BASE = "https://api.your-current-provider.example"
+ const BASE = "https://api.querying.ai"
```

把 API 密钥常量换成 querying.ai 的密钥。webhook URL、幂等键、任务类型和响应解析都保持原样。

## 已实现的内容

<CardGroup cols={2}>
  <Card title="已支持" icon="check">
    `POST /v1/async/task`

    `POST /v1/async/task/batch`

    `GET /v1/async/task/{id}`

    Webhook 回调
  </Card>

  <Card title="未实现" icon="x">
    `/v1/monitor/*` 同步端点

    `/v1/async/status`
  </Card>
</CardGroup>

同步的 `/v1/monitor/*` 系列是有意缺席的。这里的每个引擎都异步运行；在一次查询所需的时间内阻塞请求，并不是本服务提供的形态。

## 行为不同之处

<AccordionGroup>
  <Accordion title="1. 没有速率限制，请使用批量" icon="gauge">
    没有按密钥的速率限制。大量请求请使用批量提交以减少往返次数。

    请参阅[地区与最佳实践](/zh/engines/capacity)。
  </Accordion>

  <Accordion title="2. 额度按引擎计算" icon="coins">
    `credits` 作为信封的一部分出现在每个响应中。提交和轮询响应报告 `{ "creditsToCharge": 0, "creditsCharged": 0 }`；
    webhook 报告按引擎计算的额度消耗（视引擎为 1–3 额度）。

    失败的任务不计费。额度余额可在控制台查看。
  </Accordion>

  <Accordion title="3. 部分引擎 × 地区组合会被直接拒绝" icon="ban">
    有一种组合完全无法服务：`CHATGPT`/`PERPLEXITY`/`GEMINI` 发往 `CN`，那里没有出口供给，请求永远到不了目标。
    它会立即以 `422 REGION_UNSUPPORTED` 失败，而不是被接受。`422 REGION_UNAVAILABLE` 则对应同一情况的暂时版本。

    假定所有格式正确的提交都会被接受的客户端，需要在这里增加分支。请参阅[地区](/zh/engines/capacity)。
  </Accordion>

  <Accordion title="4. include 标志大多不起作用" icon="toggle-left">
    `payload.include` 标志会被接受，但这里的大多数引擎返回固定结构的响应并忽略它们。只有 ChatGPT 支持全部标志；
    `GEMINI` 只支持 `markdown` 和 `rawResponse`。

    例如向 Gemini 请求 `html` 会被静默忽略，不报错，也没有该字段。请参阅[标志支持表](/zh/engines/overview)。
  </Accordion>

  <Accordion title="5. 多了一个状态码：422" icon="hash">
    其余错误处理都很常规：校验失败返回 `400`，`401` 报告 `MISSING_API_KEY`，`404` 报告 `RESOURCE_NOT_FOUND`，
    `details` 指出出错字段。

    唯一新增的是上文描述的 `422` 两个错误码（`REGION_UNSUPPORTED`、`REGION_UNAVAILABLE`）。我们会预先告知某地区
    无法服务，因此从未处理过 `422` 的客户端会开始收到它们。
  </Accordion>

  <Accordion title="6. 失败任务会多出顶层 `error` 字符串" icon="triangle-alert">
    对 `FAILED` 任务调用 `GET /v1/async/task/{id}` 会返回一个任务状态结构中未另行定义的顶层 `error` 字段，
    而且它是**普通字符串**，不是请求级错误使用的 `{code, message, timestamp}` 对象。

    ```json theme={null}
    { "success": true, "task": { "status": "FAILED", "...": "..." }, "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline." }
    ```

    把 `body.error` 为真视为*请求*失败的客户端，会误读一个成功取回的失败*任务*。请改为按 `task.status` 分支。
  </Accordion>
</AccordionGroup>

<Note>
  这些行为是通过实际调用本 API 确认的，而不是阅读结构定义得出的。当公开规范与实际响应不一致时，本文档以实际响应为准。
</Note>

## 选择合适的 `taskType`

如果你当前的集成调用的是按引擎划分的端点，引擎名称对应如下 `taskType`：

| 原先调用的 | `taskType` |
| - | - |
| ChatGPT | `CHATGPT` |
| Perplexity | `PERPLEXITY` |
| Gemini | `GEMINI` |
| Google AI 模式 | `AIMODE` |
| Google AI 概览 | `GOOGLE` |
| Naver | `NAVER_AI_BRIEF` / `NAVER_AI_TAB` |

<Note>
  `GOOGLE` 表示“AI 概览”只是命名惯例，并非 Google 的产品名。响应是一个把 `aioverview` 作为可空成员的 SERP 信封，
  请参阅 [GOOGLE 响应结构](/zh/engines/overview)。
</Note>

## 验证切换

让现有集成与本集成并行运行一段时间，并比对你实际使用的字段，通常是 `response.text`、`response.sources[]`
和 `response.markdown`。影子对比能发现结构检查发现不了的差异，例如来源列表已填充但顺序不同。