> ## 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.

# AI 搜索数据 API 快速入门

> 提交任务，通过 webhook 或轮询获取结果。

[入门指南](https://querying.ai/zh/guides/quickstart) · [API 套餐与额度](https://querying.ai/zh/pricing)

## 1. 设置凭据

```bash theme={null}
export BASE="https://api.querying.ai"
export API_KEY="<your-key>"
```

## 2. 提交任务

向 Gemini 提一个问题。`taskType` 选择引擎，`payload.prompt` 是你要问的内容。

```bash theme={null}
curl -X POST "$BASE/v1/async/task" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "GEMINI",
    "payload": { "prompt": "best wireless earbuds 2026", "country": "US" }
  }'
```

任务被接受并进入队列：

```json theme={null}
{
  "success": true,
  "task": {
    "id": "8f2c1e40-...",
    "taskType": "GEMINI",
    "status": "QUEUED",
    "priority": 1,
    "createdAt": "2026-07-09T04:12:00.000Z"
  },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
}
```

<Note>
  `credits` 是响应信封的一部分。提交和轮询时它始终为零；webhook 会报告按引擎计算的额度消耗（公开回答引擎为
  1–2 额度，Prompt Research 为 12 额度，Source Influence 单独计量）。余额可在控制台查看。
</Note>

## 3. 获取结果

<Tabs>
  <Tab title="Webhook（推荐）">
    提交时加上 `webhook.url`。任务进入终止状态后，我们会把完整结果 POST 到该地址，你无需轮询。

    ```bash theme={null}
    curl -X POST "$BASE/v1/async/task" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "taskType": "GEMINI",
        "payload": { "prompt": "best wireless earbuds 2026" },
        "webhook": { "url": "https://your-server.example.com/hook" }
      }'
    ```

    你的端点会收到 `{ task, credits, response }`。投递与重试约定请参阅 [Webhook](/zh/concepts/webhooks)。
  </Tab>

  <Tab title="轮询">
    省略 `webhook`，按 id 轮询任务。任务进入终止状态前不会有 `response`。

    ```bash theme={null}
    curl "$BASE/v1/async/task/8f2c1e40-..." \
      -H "Authorization: Bearer $API_KEY"
    ```

    ```json theme={null}
    {
      "success": true,
      "task": { "id": "8f2c1e40-...", "status": "COMPLETED", "...": "..." },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
      "response": {
        "text": "The best wireless earbuds in 2026 are ...",
        "sources": [{ "position": 1, "url": "https://...", "label": "..." }]
      }
    }
    ```

    <Warning>
      公开轮询在任务完成后 24 小时内可用。请在此期间内轮询，否则已完成的任务也会因过期返回 404。
    </Warning>
  </Tab>
</Tabs>

## 4. 批量提交

`POST /v1/async/task/batch` 接收由相同任务对象组成的 JSON **数组**，每个请求最多 500 个。同一批次中可以
自由混用不同引擎。

```bash theme={null}
curl -X POST "$BASE/v1/async/task/batch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "taskType": "GEMINI",     "payload": { "prompt": "best wireless earbuds 2026" } },
    { "taskType": "PERPLEXITY", "payload": { "prompt": "best wireless earbuds 2026" } },
    { "taskType": "GOOGLE",     "payload": { "query":  "best wireless earbuds 2026" } }
  ]'
```

格式正确的批量请求始终返回 `200`。单个失败会以 `results[].success = false` 呈现，一个错误任务不会拖垮其余任务。
请参阅[批量提交](/zh/api-reference/create-task-batch)。

<Note>
  Google 系引擎（`GOOGLE`、`AIMODE`、`NAVER_*`）读取 `payload.query`，LLM 引擎读取 `payload.prompt`。
  提供任意一个都能通过校验，但引擎会优先读取它期望的那个字段。
</Note>

## 下一步

<CardGroup cols={2}>
  <Card title="选择引擎" icon="cpu" href="/zh/engines/overview">
    所有 `taskType` 及其返回内容。
  </Card>

  <Card title="处理失败" icon="triangle-alert" href="/zh/concepts/errors">
    错误码、状态码，以及哪些可以重试。
  </Card>
</CardGroup>