> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/api-reference/cn/he-xin-duan-dian.md).

# 核心端点

Web API 两个核心端点 /search 和 /scrape 的参考——参数、响应架构和示例。

<table><thead><tr><th width="184">端点</th><th>返回</th></tr></thead><tbody><tr><td><a href="#post-v1-search"><code>/search</code></a></td><td>按排名排序的自然网页结果</td></tr><tr><td><a href="#post-v1-scrape"><code>/scrape</code></a></td><td>从 URL 提取内容</td></tr></tbody></table>

### `POST /v1/search`

按排名排序的自然网页结果。

**模式：** `同步` 仅

#### **请求架构**

```bash
curl https://webapi.oxylabs.io/v1/search \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "eu ai act compliance deadlines", "max_results": 3, "location": "DE"}'
```

<table><thead><tr><th width="122">参数</th><th width="88.5">类型</th><th width="84.5">必需</th><th>说明</th></tr></thead><tbody><tr><td><code>query</code></td><td>字符串</td><td>是</td><td>关键词搜索短语。 <code>1</code> 到 <code>2048</code> 字符。</td></tr><tr><td><code>max_results</code></td><td>整数</td><td>否</td><td>要返回的结果数量。 <code>1</code>–<code>20</code>。默认 <code>10</code></td></tr><tr><td><code>location</code></td><td>字符串</td><td>否</td><td>ISO 3166-1 alpha-2 国家代码，例如 <code>DE</code>。默认 <code>null</code></td></tr></tbody></table>

#### **响应**

{% code expandable="true" %}

```json
{
  "state": "done",
  "results": [
    {
      "title": "Implementation Timeline | EU Artificial Intelligence Act",
      "outline": [
        "Date 2 August 2025 Providers: need to be compliant..."
      ],
      "url": "https://artificialintelligenceact.eu/implementation-timeline/",
      "metadata": {
        "position": 1
      }
    }
  ],
  "related_questions": [
    {
      "question": "When does the EU AI Act take effect?",
      "title": "Implementation Timeline | EU Artificial Intelligence Act",
      "snippet": "The Act applies in stages, beginning in August 2024."
    }
  ],
  "related_searches": [
    { "query": "ai act timeline" }
  ],
  "params": {
    "query": "eu ai act compliance deadlines",
    "location": "DE",
    "max_results": 3
  },
  "metadata": {
    "timestamp": 1787431568,
    "request_id": "1788875675880097469"
  }
}
```

{% endcode %}

<table><thead><tr><th width="265">字段</th><th width="84">类型</th><th>说明</th></tr></thead><tbody><tr><td><code>state</code></td><td>字符串</td><td><code>done</code>. <code>faulted</code> 在一个 <code>500</code></td></tr><tr><td><code>results[]</code></td><td>数组</td><td>按排名排序的自然结果，优先最佳。未匹配到任何内容时为空</td></tr><tr><td><code>results[].title</code></td><td>字符串</td><td>页面标题</td></tr><tr><td><code>results[].outline</code></td><td>字符串数组</td><td>内容摘要。每项均已截断</td></tr><tr><td><code>results[].url</code></td><td>字符串</td><td>结果的绝对 URL</td></tr><tr><td><code>results[].metadata.position</code></td><td>整数</td><td>排名，从 <code>1</code></td></tr><tr><td><code>related_questions[]</code></td><td>数组</td><td>“People also ask” 条目。为空时省略</td></tr><tr><td><code>related_questions[].question</code></td><td>字符串</td><td>问题。始终存在</td></tr><tr><td><code>related_questions[].title</code></td><td>字符串</td><td>回答页面标题 <em>（可选）</em></td></tr><tr><td><code>related_questions[].snippet</code></td><td>字符串</td><td>回答该问题的摘录。已截断 <em>（可选）</em></td></tr><tr><td><code>related_searches[]</code></td><td>数组</td><td>相关查询，每个都有一个 <code>query</code>。为空时省略</td></tr><tr><td><code>params</code></td><td>对象</td><td>请求使用的参数，默认值已填充</td></tr><tr><td><code>metadata.timestamp</code></td><td>整数</td><td>Unix 时间戳，单位为秒</td></tr><tr><td><code>metadata.request_id</code></td><td>字符串</td><td>请求标识符</td></tr></tbody></table>

### `POST /v1/scrape`

从 URL 提取数据，并以请求的格式返回其内容。

**模式：** `同步`, `异步`, `批量`

#### **请求架构**

```bash
curl https://webapi.oxylabs.io/v1/scrape \
  -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://artificialintelligenceact.eu/implementation-timeline/", "output": ["markdown"]}'
```

<table><thead><tr><th width="133">参数</th><th width="93">类型</th><th width="90">必需</th><th>说明</th></tr></thead><tbody><tr><td><code>url</code></td><td>字符串</td><td>是</td><td>绝对 <code>http</code> 或 <code>https</code> URL。请保持原样发送，查询字符串和路径段很重要</td></tr><tr><td><code>output</code></td><td>字符串数组</td><td>否</td><td>要返回的格式： <code>["html"]</code> （默认）， <code>["markdown"]</code>, <code>["json"]</code>, <code>["screenshot"]</code>.<br><code>json</code> 返回解析后的字段（通过专用解析器或 <a href="/products/web-api/scrape/ai-parsing.md">AI 解析</a>). <code>screenshot</code> 需要 <code>run_js: true</code></td></tr><tr><td><code>json</code></td><td>对象</td><td>否</td><td>当……时必需 <code>output</code> 包含 <code>json</code> （且没有可用的专用解析器）： <code>{"prompt": string}</code> 或 <code>{"schema": object}</code>，不能同时使用</td></tr><tr><td><code>json.prompt</code></td><td>字符串</td><td>否</td><td>面向自然语言的提取指令，用于 <code>output: ["json"]</code>. <code>max_len: 8192</code>，默认： <code>null</code>。不能与 <code>json.schema</code>.</td></tr><tr><td><code>json.schema</code></td><td>对象</td><td>否</td><td>定义所需 JSON 输出结构的 OpenAPI / JSON Schema 对象。 <code>10</code> 到 <code>65535</code> 字符，默认： <code>null</code>。不能与 <code>json.prompt</code></td></tr><tr><td><code>location</code></td><td>字符串</td><td>否</td><td>用于抓取的两字母国家代码，例如 <code>DE</code></td></tr><tr><td><code>device</code></td><td>字符串</td><td>否</td><td><code>桌面端</code> （默认）或 <code>移动端</code></td></tr><tr><td><code>run_js</code></td><td>布尔值</td><td>否</td><td>在抓取前执行页面 JavaScript。速度更慢，请使用 150 秒或更长的客户端超时</td></tr><tr><td><code>callback_url</code></td><td>字符串</td><td>否</td><td><strong>仅异步。</strong> 任务完成后的 Webhook URL。格式错误的 URL 将被拒绝，并返回 <code>400</code></td></tr><tr><td><code>storage</code></td><td>对象</td><td>否</td><td><strong>仅限异步。</strong> 将结果投递到存储桶，而不是响应： <code>{"type": string, "url": string}</code>. <code>type</code> 为 <code>s3</code>, <code>s3_gzip</code>, <code>s3_compatible</code>, <code>gcs</code>，或 <code>tos</code>. <code>url</code> 不进行校验</td></tr></tbody></table>

{% hint style="warning" %}
带有 **专用解析器** （例如 [Bed Bath & Beyond 产品页](/api-reference/cn/zhuan-yong-zhua-qu-qi/dian-shang-zhua-qu-qi.md#post-v1-scrape-bedbathandbeyond-product)）会自动解析，不需要 `json` 带有 `prompt` 或 `schema`。包含它们会覆盖现有的专用解析器。
{% endhint %}

#### **响应**

{% code expandable="true" %}

```json
{
  "state": "done",
  "results": [
    {
      "html": "107.175.25.67\n",
      "metadata": {
        "page": 1,
        "run_js": false,
        "url": "https://ip.oxylabs.io/",
        "statuses": {
          "http_request": {
            "code": 200,
            "tag": "HTTP_OK"
          }
        }
      }
    }
  ],
  "params": {
    "url": "https://ip.oxylabs.io",
    "output": ["html"],
    "json": { "schema": null, "prompt": null },
    "location": null,
    "device": "desktop",
    "run_js": null,
    "storage": {
      "type": "s3",
      "url": "oxylabs.test/7517848208047890433.json"
    },
    "callback_url": null,
    "client_notes": null
  },
  "metadata": {
    "timestamp": 1792394688,
    "request_id": "7517848208047890433",
    "statuses": {
      "storage_upload": {
        "code": 13000,
        "tag": "UPLOAD_SUCCESS"
      }
    }
  }
}
```

{% endcode %}

<table><thead><tr><th width="215">字段</th><th width="81">类型</th><th>说明</th></tr></thead><tbody><tr><td><code>state</code></td><td>字符串</td><td><code>done</code>, <code>待处理</code>，或 <code>faulted</code></td></tr><tr><td><code>状态</code></td><td>整数</td><td>在错误响应中返回。HTTP 状态码</td></tr><tr><td><code>results[]</code></td><td>数组</td><td>所请求 URL 对应的一条记录。当……时返回 <code>state</code> 为 <code>done</code></td></tr><tr><td><code>results[].markdown</code></td><td>字符串</td><td>页面的 Markdown 版本。请求时返回</td></tr><tr><td><code>results[].html</code></td><td>字符串</td><td>原始标记内容。请求时返回</td></tr><tr><td><code>results[].json</code></td><td>对象</td><td>解析后的字段。请求时返回</td></tr><tr><td><code>results[].screenshot</code></td><td>字符串</td><td>截图。请求时返回</td></tr><tr><td><code>results[].metadata.url</code></td><td>字符串</td><td>重定向后的抓取 URL</td></tr><tr><td><code>results[].metadata.statuses</code></td><td>对象</td><td>HTTP、解析及其他带标签的处理状态</td></tr><tr><td><code>params</code></td><td>对象</td><td>请求使用的参数，默认值已填充。保留 null 值</td></tr><tr><td><code>metadata.timestamp</code></td><td>整数</td><td>Unix 时间戳，单位为秒</td></tr><tr><td><code>metadata.request_id</code></td><td>字符串</td><td>请求标识符</td></tr><tr><td><code>metadata.statuses</code></td><td>对象</td><td>带标签的请求级状态，例如存储投递状态</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/api-reference/cn/he-xin-duan-dian.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.