基础工具1 credit

extract_metadata

提取全面的页面元数据，包括标题、描述、OpenGraph 标签、Twitter Card 数据和 SEO 信息。

使用场景

SEO 分析

分析页面标题、描述和关键词以进行优化

社交媒体预览数据

获取 OpenGraph 和 Twitter Card 数据，用于丰富的社交预览

内容分类

使用元数据对网页内容进行分类和整理

生成链接预览

用标题、图片和描述构建丰富的链接预览

Endpoint

POST/api/v1/tools/extract_metadata

Auth Required

Free 计划 1 req/s

1 credit

Parameters

Name	Type	Required	Default	Description
url	string	Optional	-	要从中提取元数据的页面。`url` 与 `html` 二者必填其一。 Example: https://example.com/article
html	string	Optional	-	直接解析的原始 HTML，替代抓取。 Example: <html>...</html>
include_social	boolean	Optional	true	包含 Open Graph、Twitter 卡片、Facebook app id 与站点验证标签。 Example: true
include_seo	boolean	Optional	true	包含 description、keywords、author、robots、canonical、标题层级与 viewport。 Example: true
include_technical	boolean	Optional	true	包含 generator、favicon、样式表与脚本。 Example: true
include_structured_data	boolean	Optional	true	包含页面上找到的 JSON-LD 结构化数据块。 Example: true
respect_robots	boolean	Optional	true	遵守目标站点的 robots.txt。保持 `true` 时，robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝，且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到你的 API key 上。 Example: true
max_inline_chars	number	Optional	40000	内联返回的最大结果大小，以其 JSON 的字符数计（1,000-10,000,000）。超过后，响应会携带 `preview`（格式化 JSON 的前 `max_inline_chars` 个字符）、`result_handle`、`total_chars`、`truncated: true` 和 `expires_at`，其余部分由 [read_result](/docs/api-reference/tools/read-result) 读取，每次调用 1 credit。已存储的结果保留 1 小时。 Example: 40000

请求示例

cURL

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/extract_metadata \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

TypeScript

extractMetadata.tsTypescript

// npm install crawlforge-sdk
import { CrawlForge } from 'crawlforge-sdk';

const client = new CrawlForge({ apiKey: process.env.CRAWLFORGE_API_KEY });

const result = await client.extractMetadata({
  url: 'https://example.com/article',
});

// result.data is untyped in crawlforge-sdk 0.1 — its shape is the Response Example below.
const { metadata } = result.data as {
  metadata: {
    basic: { title: string };
    seo: { description: string };
    social: { open_graph: { image?: string } | null; twitter: { card?: string } | null };
  };
};
console.log('Title:', metadata.basic.title);
console.log('Description:', metadata.seo.description);
// open_graph and twitter are null when the page declares no such tags.
console.log('OG Image:', metadata.social.open_graph?.image);
console.log('Twitter Card:', metadata.social.twitter?.card);

Python

extract_metadata.pyPython

# pip install crawlforge
from crawlforge import CrawlForge

client = CrawlForge()  # reads CRAWLFORGE_API_KEY

result = client.extract_metadata(
    url='https://example.com/article',
)

# result.data is a plain dict — its shape is the Response Example below.
metadata = result.data['metadata']
print(f"Title: {metadata['basic']['title']}")
print(f"Description: {metadata['seo']['description']}")
# open_graph and twitter are None when the page declares no such tags.
open_graph = metadata['social']['open_graph'] or {}
twitter = metadata['social']['twitter'] or {}
print(f"OG Image: {open_graph.get('image')}")
print(f"Twitter Card: {twitter.get('card')}")

响应示例

200 OK195ms

{
  "success": true,
  "data": {
    "metadata": {
      "basic": {
        "title": "Example Article - Best Practices Guide",
        "url": "https://example.com/article",
        "lang": "en",
        "charset": "utf-8"
      },
      "seo": {
        "description": "Learn the best practices for web development",
        "keywords": "web development, best practices, tutorial",
        "author": "Jane Doe",
        "robots": "index, follow",
        "canonical": "https://example.com/article",
        "headings": {
          "h1": [
            "Best Practices Guide"
          ],
          "h2": [
            "Getting Started",
            "Common Pitfalls"
          ],
          "h3": []
        },
        "meta_refresh": null,
        "viewport": "width=device-width, initial-scale=1"
      },
      "social": {
        "open_graph": {
          "title": "Example Article - Best Practices Guide",
          "image": "https://example.com/og-image.jpg",
          "type": "article",
          "site_name": "Example Site"
        },
        "twitter": {
          "card": "summary_large_image",
          "site": "@examplesite"
        },
        "facebook_app_id": null,
        "google_site_verification": null
      },
      "technical": {
        "generator": "Next.js",
        "favicons": [
          {
            "rel": "icon",
            "href": "/favicon.ico",
            "type": "image/x-icon"
          }
        ]
      },
      "structured_data": []
    },
    "summary": {
      "has_title": true,
      "has_description": true,
      "has_open_graph": true,
      "has_twitter_cards": true,
      "has_structured_data": false,
      "total_headings": 3
    },
    "extracted_from": "https://example.com/article",
    "redirected": false,
    "extraction_time": "2026-08-26T14:30:00.000Z"
  },
  "credits_used": 1,
  "credits_remaining": 999,
  "processing_time": 195
}

Field Descriptions

data.metadata.basic始终存在：标题、解析后的 url、html 的 lang 与字符集。

data.metadata.seo当 `include_seo` 为 true 时出现。包含完整的 h1/h2/h3 标题层级结构。

data.metadata.social.open_graph页面声明的全部 `og:` 属性，原样返回。页面没有声明时为 null。

data.metadata.social.twitter页面声明的全部 `twitter:` 属性。没有时为 null。

data.metadata.technical当 `include_technical` 为 true 时出现：generator、favicon、样式表与脚本。

data.metadata.structured_data页面上找到的 JSON-LD 块。没有时为空数组。

data.summary一组布尔值，便于快速检查完整性，无需遍历整个 metadata 对象。

data.extracted_from来源 URL（即经过任何重定向后的最终 URL）；若您传入的是 `html`，则为字面量字符串 'provided HTML'。

data.redirected始终存在。抓取最终落在与您发送的 URL 不同的地址时为 `true`；两者在解析后再比较，因此 `https://example.com` 与 `https://example.com/` 视为同一页面。此时元数据描述的是重定向后的页面，`data.requested_url` 给出您发送的 URL。传入 `html` 时始终为 `false`。

data.extraction_time本次提取的 ISO 8601 时间戳。

错误处理

被 robots.txt 拦截（403 Forbidden）

目标站点的 robots.txt 对 CrawlForge 禁止了该路径。若你与目标站点另有约定，可设置 respect_robots: false 予以覆盖——该覆盖会记录到你的 API key 上。该覆盖不适用于列入 CrawlForge 永久排除名单的主机——无论 respect_robots 取何值，这类主机一律被拒绝。