WebExtrator 智能抽取 API 集成指南

POST https://api.acedata.cloud/webextrator/extract WebExtrator 智能抽取 API 把一个 URL 转换成類型化的結構化結果 —— 文章、商品、食譜、視頻、討論、招聘等，同時附帶清洗後的 Markdown 與純文本。當你想要”乾淨的結構化數據”而不是原始 HTML 時，這是該用的接口。底層是一條三層流水線：

schema.org JSON-LD 映射器 —— 確定性、零 LLM 成本。覆蓋 Wikipedia / BestBuy / AllRecipes / YouTube / 大部分新聞 / 大部分商品頁。
類型化 LLM 抽取 —— 僅在 schema.org 未命中時觸發。按頁面類型選 Schema， Zod 嚴格校驗。
Readability + Markdown 兜底 —— 始終運行，補齊前兩層沒填的頂層字段。

URL 重複請求會被 Redis 結果快取接住，<1 ms 返回。

申請流程

要使用 WebExtrator 服務頁，首先到 Ace Data Cloud 控制台獲取您的 API Token，留作備用。

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。 一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在控制台充值通用餘額。

📘 完整文檔：WebExtrator 服務頁 →

鑑權

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

請求參數

Extract 接受所有Render API 的參數（url、user_agent、timeout、wait_until、delay、wait_for_selector、 block_resources、headers、cookies、callback_url、bypass_cache、 cache_ttl_seconds、async），外加兩個 Extract 專屬字段：

字段	類型	必填	默認	說明
`expected_type`	enum	❌	自動判斷	頁面類型提示：`product` / `article` / `general`。跳過 URL / 文本啟發式，直接走對應分支。
`enable_llm`	boolean	❌	`false`	當 schema.org 未命中時允許調用 LLM 抽取。在 Amazon / HN / Greenhouse 這類無 JSON-LD 的頁面上，需要打開才能拿到類型化結果。

當頁面自帶 schema.org JSON-LD 時，enable_llm 無效 —— 確定性映射器直接出結果，永遠不會浪費 LLM 調用。你白嫖到類型化結果。

同步響應

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_at": 1777717800.123,
  "finished_at": 1777717802.535,
  "elapsed": 2.412,
  "data": {
    "kind": "extract",
    "url": "https://en.wikipedia.org/wiki/Diffbot",
    "finalUrl": "https://en.wikipedia.org/wiki/Diffbot",
    "contentType": "article",
    "title": "Diffbot",
    "description": "美國機器學習和知識管理公司",
    "byline": "維基媒體項目的貢獻者",
    "language": "en",
    "siteName": "Wikipedia",
    "publishedAt": "2007-08-08T05:47:27Z",
    "images": ["https://en.wikipedia.org/static/images/icons/enwiki-25.svg"],
    "links": ["https://en.wikipedia.org/wiki/Machine_learning"],
    "markdown": "# Diffbot\n\nDiffbot is a developer of machine learning ...",
    "text": "Diffbot is a developer of machine learning algorithms ...",
    "structured": {
      "schemaOrg": { "primary": { /* 類型化實體 */ }, "breadcrumbs": [], "all": [] },
      "openGraph": { "title": "...", "description": "...", "image": "...", "type": "..." },
      "jsonLd": [ /* 原始 JSON-LD */ ]
    },
    "rawSignals": {
      "hasJsonLd": true,
      "title": "Diffbot - Wikipedia",
      "metaDescription": null,
      "pageStatus": 200,
      "textLength": 11473
    },
    "elapsedMs": 2412
  }
}

頂層字段

字段	類型	說明
`kind`	string	固定 `"extract"`。
`url`	string	你提交的 URL。
`finalUrl`	string	重定向後的最終 URL。
`contentType`	enum	`product` / `article` / `general`，由 `expected_type` → schema.org primary → 啟發式依次確定。
`title`	string	Readability `<title>` 或渲染後的 `document.title`。
`description`	string?	優先級：`<meta name="description" />` → `og:description` → schema.org / LLM 抽取 → 正文首段截斷。
`byline`	string?	作者 / 頻道 / 公司。來源 `<meta name="author" />` → schema.org / LLM。
`language`	string?	`<html lang>`。
`siteName`	string?	`og:site_name`。
`publishedAt`	string?	ISO 8601。優先級：`article:published_time` → `<time datetime>` → schema.org / LLM。
`images`	string[]	最多 50 個 `<img src />`，已解析為絕對 URL、去重、丟棄 `data:` URI。
`links`	string[]	最多 100 個外鏈，已過濾片段 / `javascript:` / `mailto:` / `tel:`。
`markdown`	string	Turndown 轉出的 Markdown。
`text`	string	Mozilla Readability 抽取的 `textContent`。
`structured`	object	完整結構化結果，見下。
`rawSignals`	object	調試用的診斷信息。
`cached`	boolean?	命中快取時為 `true`。
`cacheStoredAt`	number?	快取條目首次寫入的 Unix 毫秒時間戳。

`data.structured` 子字段

子字段	何时出现	说明
`schemaOrg`	始终	`{ primary, breadcrumbs, all }`。`primary` 是最高优先级的类型化实体；找不到时为 `null`。
`openGraph`	始终	`{ title, description, image, type }`，源自 `<meta property="og:*" />`。
`jsonLd`	始终	所有 `<script type="application/ld+json">` 块的原始 JSON 数组。
`llm`	LLM 跑了且成功时	`{ kind, data, model, promptCharCount }`，Zod 校验过的类型化结果。
`llmError`	LLM 跑了但失败时	`{ kind, error, model }`，请求不会因此挂掉，启发式结果依然返回。
`amazon`	URL 是 `amazon.*` 时	老的 amazon 专用抓取器结果（将逐步废弃）。

schema.org 映射器覆盖范围

按优先级排序（命中即作为 structured.schemaOrg.primary）：

schema.org 类型	映射 kind	输出字段
`Product`	product	`name, sku, gtin, model, color, brand, url, images, offer.{price,currency,availability,condition,seller}, rating.{value,count}, reviews[], properties[]`
`Recipe`	recipe	`name, description, image, datePublished, author, cookTime, prepTime, totalTime, recipeYield, ingredients[], instructions[], nutrition, rating, keywords, recipeCategory, recipeCuisine`
`VideoObject`	video	`name, description, thumbnailUrl, uploadDate, duration, embedUrl, contentUrl, channel, interactionCount`
`JobPosting`	job	`title, description, datePosted, validThrough, hiringOrganization, jobLocation, baseSalary, employmentType`
`Event`（含 `*Event`）	event	`name, description, startDate, endDate, location.{name,address}, organizer, offer.{url,price,currency}`
`Article` / `NewsArticle` / `BlogPosting` / `ScholarlyArticle` / `TechArticle` / `Report` / `*NewsArticle`	article	`subtype, headline, description, datePublished, dateModified, author, publisher, image[], url, sameAs[]`
`FAQPage`	faq	`questions[{question, answer}]`
`BreadcrumbList`	（挂在 sibling）	始终输出到 `structured.schemaOrg.breadcrumbs[]`，不会作为 primary。

映射器处理：

@graph 容器（递归展开）；
@type 数组（如 ["Recipe", "NewsArticle"] —— 两个都识别，按优先级取胜）；
http://schema.org/ 前缀变体；
嵌套 Offer 与 AggregateOffer（后者读 lowPrice）；
相对图像 URL（按 finalUrl 解析为绝对）。

LLM 类型化 Schema

当 enable_llm: true 且 schema.org 没有 primary 时，抽取器按 URL 启发式（或 expected_type 提示）选下面之一的 Zod Schema 校验模型输出：

Kind	URL 启发式	必填字段	可选字段
`article`	文本 ≥400 字且其它未命中	`headline`	`description, byline, publishedAt, language, topics[], sections[{heading,summary}]`
`product`	`amazon.* / ebay.* / aliexpress.* / temu.* / walmart.* / bestbuy.*`	`name`	`description, brand, sku, price, currency, availability, rating.{value,count}, bullets[], specifications[{name,value}]`
`discussion`	`news.ycombinator.com / reddit.com / lobste.rs`	`title`	`author, postedAt, points, commentCount, body, url`
`recipe`	`allrecipes / foodnetwork / seriouseats / epicurious / bonappetit / simplyrecipes`	`name`	`description, author, cookTime, prepTime, totalTime, recipeYield, ingredients[], instructions[], nutrition, rating, keywords[]`
`video`	`youtube.com/watch / youtu.be / vimeo.com/<id> / tiktok.com/@/video`	`name`	`description, channel, uploadDate, duration, viewCount, likeCount, thumbnailUrl, transcript`
`job`	`greenhouse.io / lever.co / jobs.* / careers.* / workable.com / bamboohr`	`title`	`description, company, location, remote, employmentType, datePosted, validThrough, salaryMin, salaryMax, salaryCurrency, salaryPeriod, responsibilities[], qualifications[]`

LLM 成功时还会向顶层字段做”last-resort”回填：

article → description / byline / publishedAt / language
product → description
discussion → description（= body 前 280 字）/ byline（= author）/ publishedAt（= postedAt）
recipe → description / byline（= author）
video → description / byline（= channel）/ publishedAt（= uploadDate）
job → description / byline（= company）/ publishedAt（= datePosted）

回填只在确定性数据源没填对应字段时触发 —— LLM 始终是最后一道兜底。

缓存

相同请求会被哈希到同一个 Redis Key： webextrator:cache:extract:<sha256(canonical-json)>。缓存 Key 忽略 async、 bypass_cache、cache_ttl_seconds（这是操作开关，不影响响应）。cookies / headers 会分桶缓存。

字段	效果
`bypass_cache: true`	跳过读取；本次结果仍会写回缓存，下次相同请求能命中。
`cache_ttl_seconds: 0`	本次响应不缓存。
`cache_ttl_seconds: N`	自定义本条目的 TTL（默认 3600 秒）。

命中缓存的响应会带上 data.cached: true 与 data.cacheStoredAt: <unix-ms>。

异步模式与回调

设置 async: true 进入异步模式（提供 callback_url 也会自动进入）。平台立即返回（HTTP 200）：

{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}

任务完成时把完整 envelope POST 到你的 callback_url（如果配置了）。也可以事后通过 /webextrator/tasks 主动查询。

示例

1. Wikipedia 文章（schema.org 命中，不需要 LLM）

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://en.wikipedia.org/wiki/Diffbot",
    "expected_type": "article"
  }'

data.structured.schemaOrg.primary 关键字段：

{
  "kind": "article",
  "subtype": "Article",
  "headline": "美國機器學習與知識管理公司",
  "datePublished": "2007-08-08T05:47:27Z",
  "dateModified": "2025-07-10T20:42:45Z",
  "author": { "name": "維基媒體項目的貢獻者", "type": "Organization" },
  "publisher": { "name": "維基媒體基金會, Inc." }
}

2. BestBuy 商品页（schema.org 命中）

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.bestbuy.com/product/apple-airpods-pro-2nd-generation-white/JJ8ZH6TPSW",
    "expected_type": "product"
  }'

schema.org 抽出：

{
  "kind": "product",
  "name": "Apple - 翻新優良 - AirPods Pro (第二代) - 白色",
  "sku": "10845412",
  "model": "MQD83AM/A",
  "color": "白色",
  "brand": "Apple",
  "offer": { "price": 159.99, "currency": "USD", "availability": "https://schema.org/InStock", "seller": "Best Buy" },
  "rating": { "value": 4.4, "count": 8 }
}

3. AllRecipes 食谱页（含营养与步骤）

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.allrecipes.com/recipe/16354/easy-meatloaf/"
  }'

schema.org 抽出：

{
  "kind": "recipe",
  "name": "簡易肉餅",
  "cookTime": "PT60M",
  "totalTime": "PT75M",
  "recipeYield": "8 / 1 (9x5-inch) 肉餅",
  "ingredients": ["1 1/2 磅絞牛肉", "..."],
  "instructions": [{ "text": "預熱烤箱至 350°F ..." }, "..."],
  "rating": { "value": 4.7, "count": 9348 }
}

4. HN 讨论页（无 JSON-LD —— 需要启用 LLM）

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com/item?id=37000000",
    "enable_llm": true
  }'

data.structured.llm.data：

{
  "kind": "discussion",
  "title": "Show HN: 一種提取網頁的新方法",
  "author": "alice",
  "points": 173,
  "commentCount": 42,
  "body": "嗨 HN，我們建立了一個自我托管的替代方案來取代 Diffbot 的分析 API ..."
}

顶层字段也被回填：byline = "alice"、publishedAt = "..."。

5. Amazon 商品页（Amazon 无 JSON-LD —— 需要启用 LLM）

curl -X POST https://api.acedata.cloud/webextrator/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.amazon.com/dp/B0BSHF7WHW",
    "expected_type": "product",
    "enable_llm": true
  }'

data.structured.llm.data（类型化 product）：

{
  "kind": "product",
  "name": "Apple 2023 MacBook Pro M2 Pro 14-inch",
  "brand": "Apple",
  "price": 1799,
  "currency": "USD",
  "bullets": ["Apple M2 Pro 芯片，10 核 CPU", "..."],
  "specifications": [{ "name": "顯示尺寸", "value": "14.2 英寸" }, "..."]
}

Python (requests)

import os, requests

API_KEY = os.environ["ACEDATA_API_KEY"]

resp = requests.post(
    "https://api.acedata.cloud/webextrator/extract",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://en.wikipedia.org/wiki/Diffbot",
        "expected_type": "article",
    },
    timeout=120,
)
resp.raise_for_status()
data = resp.json()["data"]

primary = (data.get("structured") or {}).get("schemaOrg", {}).get("primary")
print("contentType:", data["contentType"])
print("title:      ", data["title"])
print("byline:     ", data.get("byline"))
print("publishedAt:", data.get("publishedAt"))
if primary and primary["kind"] == "article":
    print("headline:    ", primary["headline"])
    print("dateModified:", primary.get("dateModified"))

Node.js (fetch)

const apiKey = process.env.ACEDATA_API_KEY;

const res = await fetch('https://api.acedata.cloud/webextrator/extract', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://www.allrecipes.com/recipe/16354/easy-meatloaf/',
  }),
});
const { data } = await res.json();
const recipe = data?.structured?.schemaOrg?.primary;
console.log(recipe.name, recipe.cookTime, recipe.ingredients.length, '種配料');

提示与坑

能傳 expected_type 就傳。 免費提示，跳過啟發式判斷，對 URL 模式不在內置列表裡的頁面尤其有用。
enable_llm: true 在 schema.org 命中的頁面上是免費的。 LLM 只在 schema.org 沒有 primary 時才被調用，所以默認開著也很安全。
調試時先看 rawSignals.hasJsonLd。 如果是 true 但 structured.schemaOrg.primary 為 null，說明頁面用了我們映射器還沒覆蓋的 @type —— 提個 issue，我們加。
structured.llmError 是信息性的。 請求依然成功，啟發式結果依然返回。看 llmError.error 來定位原因（超時、JSON 解析失敗、Zod 校驗失敗）。
非文章頁的 links[] 不會做相關性排序。 僅按”上限 100 條 + 過濾無效協議” 尽力清洗。
緩存命中也計費。 緩存是為延遲和保護瀏覽器池，不是為省錢。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

代理

進階

Coding

WebExtrator 智能抽取 API 集成指南

申請流程

鑑權

請求參數

同步響應

頂層字段

`data.structured` 子字段

schema.org 映射器覆盖范围

LLM 类型化 Schema

缓存

异步模式与回调

示例

1. Wikipedia 文章（schema.org 命中，不需要 LLM）

2. BestBuy 商品页（schema.org 命中）

3. AllRecipes 食谱页（含营养与步骤）

4. HN 讨论页（无 JSON-LD —— 需要启用 LLM）

5. Amazon 商品页（Amazon 无 JSON-LD —— 需要启用 LLM）

Python (requests)

Node.js (fetch)

提示与坑

​申請流程

​鑑權

​請求參數

​同步響應

​頂層字段

​data.structured 子字段

​schema.org 映射器覆盖范围

​LLM 类型化 Schema

​缓存

​异步模式与回调

​示例

​1. Wikipedia 文章（schema.org 命中，不需要 LLM）

​2. BestBuy 商品页（schema.org 命中）

​3. AllRecipes 食谱页（含营养与步骤）

​4. HN 讨论页（无 JSON-LD —— 需要启用 LLM）

​5. Amazon 商品页（Amazon 无 JSON-LD —— 需要启用 LLM）

​Python (requests)

​Node.js (fetch)

​提示与坑

申請流程

鑑權

請求參數

同步響應

頂層字段

`data.structured` 子字段

schema.org 映射器覆盖范围

LLM 类型化 Schema

缓存

异步模式与回调

示例

1. Wikipedia 文章（schema.org 命中，不需要 LLM）

2. BestBuy 商品页（schema.org 命中）

3. AllRecipes 食谱页（含营养与步骤）

4. HN 讨论页（无 JSON-LD —— 需要启用 LLM）

5. Amazon 商品页（Amazon 无 JSON-LD —— 需要启用 LLM）

Python (requests)

Node.js (fetch)

提示与坑