webcap

webcap

截取任意 URL 的屏幕截图、提取结构化数据、监控页面变化——只需一次 HTTP API 调用。按次付费，无需账户或 API 密钥。

GET  /v1/extract/preview?url=...  →  Free preview (title, headings, links)
POST /v1/x402/capture             →  PNG/JPEG/PDF screenshot + persistent link
POST /v1/x402/extract             →  Structured JSON (title, headings, markdown)
POST /v1/x402/video               →  Scroll-capture video (WebM/VP8)
POST /v1/watches                  →  Scheduled monitoring with webhook alerts

定价：每张屏幕截图 $0.001 · 每批提取 $0.01 · 无订阅，无最低消费。

为什么选择 webcap？

特性	webcap	屏幕截图 API（常见）
价格	每张屏幕截图 $0.001	每张屏幕截图 $0.01–0.10
需要账户	否	是
API 密钥	否	是
付款方式	银行卡（Stripe）或加密货币（USDC）	仅限信用卡
批量支持	每次付款最多 50 个 URL	有限
可自托管	是（Docker）	否
开源	是（MIT）	否

功能

端点	可获取内容	价格
POST /v1/x402/capture	PNG/JPEG/PDF 格式的屏幕截图（base64）+ 持久公开的资源链接 + OG 元数据	$0.001
POST /v1/x402/extract	JSON 格式的结构化页面数据：标题、描述、标题、段落、链接、图片、字数、Markdown。每次付款最多批量处理 50 个 URL。	$0.01
POST /v1/x402/audit	一次调用即可检查 SEO 基础信息和链接/OG 状态	$0.002
POST /v1/x402/map-lite	从 sitemap/robots 获取网站 URL 列表 + 1 跳爬取（最多 50 个 URL）	$0.002
POST /v1/x402/video	滚动捕获页面并生成 WebM/VP8 视频	$0.005
POST /v1/watches	创建定时监控（免费创建，预付 100 次运行套餐）	$0.10–$1.00/套餐

Bearer 令牌支付方式（无需签名密钥）

也可以使用 API 密钥购买相同的产品：POST /v1/register （{"address"} → {apiKey}），通过普通 USDC 转账充值：调用 POST /v1/invoice，然后向 POST /v1/extract、POST /v1/audit、POST /v1/map-lite、POST /v1/video、 POST /v1/analyze 或 POST /v1/analyze/batch 发送 Authorization: Bearer <apiKey>。每次调用消耗 1 个额度；调用未返回 200 时会退还额度；余额不足时返回 402，并附带 1 个额度的充值发票。监控也使用相同的方式充值： POST /v1/watches/{id}/topup {"runs": 100}（capture 套餐为 10 个额度，extract 套餐为 100 个额度）。完整规范：GET /openapi.json（标签：accounts）。

免费端点（无需付款）

端点	说明
GET /v1/extract/preview?url=...	有限制的预览：标题、标题、链接、字数（每个 IP 每分钟 10 次请求）
GET /v1/og?url=...	Open Graph 链接预览元数据
POST /v1/watches	创建定时监控（免费；通过充值预付费用）
GET /v1/health	存活状态检查
POST /v1/feedback	向 webcap 提供反馈（机器或人工）：{"message":"…","category?"?:"bug|suggestion|pricing|docs|integration|other","endpoint"?:"…"}。无需账户，每小时限 60 次。人工填写表单：GET /feedback

快速开始

用作 MCP 服务（Agent 运行时）

webcap 附带 MCP 服务，因此任何 MCP 主机（Claude Desktop、Cursor、Agent 框架）都可以将其作为工具调用。接入方式有两种：远程端点 （完全无需安装）或从代码检出目录运行的 stdio 服务。

远程端点是 Agent 最省事的选择——无需安装、无需软件包注册表，也无需账户：

{
  "mcpServers": {
    "webcap": { "url": "https://webcap.shoutsid.fyi/mcp" }
  }
}

POST /mcp 使用 MCP Streamable HTTP（基于 HTTPS 的 JSON-RPC 2.0；GET 会 有意返回 405，因为服务不会打开 SSE 流）。它不持有钱包，因此绝不会代调用方 付款：免费工具会直接运行，付费工具则会返回实时的 x402 402 挑战，由你自己的客户端 完成结算。该端点也记录在 /.well-known/mcp-tools.json 和 openapi.json 中。

它已列入官方 MCP Registry，名称为 io.github.shoutsid-lab/webcap，因此能够读取注册表的运行时无需查看本 README 即可发现它：

curl -s 'https://registry.modelcontextprotocol.io/v0/servers?search=webcap'

stdio 服务在本地运行，并可自行结算付费调用。免费工具无需配置；设置 WEBCAP_MCP_WALLET_KEY 为 Base 主网 USDC 密钥，即可让付费工具自动结算（免 Gas——付款方 签署 EIP-3009，由 facilitator 支付 Gas）。未设置密钥时，付费工具会返回 x402 402 挑战，由主机付款。没有钱包？可改为设置 WEBCAP_MCP_API_KEY，使用由运营方注资的账户密钥（POST /v1/register，然后通过 POST /v1/invoice 注资）：付费工具会从该余额中每次扣除 1 个额度。若同时配置钱包和密钥，则优先使用钱包。

从源码检出目录开始——运行 npm ci && npm run build——然后将 args 指向 其中的 dist/mcp/stdio.js：

{
  "mcpServers": {
    "webcap": {
      "command": "node",
      "args": ["/absolute/path/to/webcap/dist/mcp/stdio.js"],
      "env": { "WEBCAP_MCP_WALLET_KEY": "0x..." }
    }
  }
}

（npm run mcp 会直接运行 TypeScript，因此无需构建。） npm 发行包将命名为 @shoutsid/webcap——无作用域的 webcap 名称属于无关的软件包，而且该发行包尚未发布——因此在此之前，上述远程端点是无需安装的选择。

全部 8 个工具（每个工具也都列在 /.well-known/openai-tools.json 和 /.well-known/mcp-tools.json 中）：

• 免费：webcap_service_catalog（所有付费端点及其价格、网络和 payTo、付款流程，以及调用方剩余的免费额度）， webcap_preview（有限预览），webcap_og
• 付费：webcap_capture（png/jpeg/pdf 截图或 PDF，或 mp4/webm 滚动 视频——始终录制为 WebM/VP8），webcap_extract（单个 URL，或最多 50 个 URL 的批量处理），webcap_audit、 webcap_map_lite、webcap_analyze

免费通道不是工具，而是一种免费额度：对五种付费工具中的任意一种发起未付款调用，都会在按 IP 滚动计算的时间窗口内免费运行真实产品（默认每 24 小时 50 次）。无需钱包、签名或账户——每个响应都会附带 x-webcap-allowance-* 标头，说明当前额度情况；窗口额度用尽后，同一调用会返回常规的 x402 402 挑战。失败的调用不会消耗额度。可通过 WEBCAP_ALLOWANCE_CALLS、 WEBCAP_ALLOWANCE_WINDOW_HOURS 和 WEBCAP_ALLOWANCE_GLOBAL_LIMIT 调整。

反馈使用 REST 通道，而非工具：POST /v1/feedback。

截取屏幕截图

# 1. POST without payment → HTTP 402 + a PAYMENT-REQUIRED header
curl -si -X POST "https://webcap.shoutsid.fyi/v1/x402/capture" \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/"}'

# 2. Decode the base64 challenge → sign a gasless EIP-3009 transfer → retry with PAYMENT-SIGNATURE

JavaScript（使用 x402 自动付款）

import axios from 'axios';
import { x402Client, wrapAxiosWithPayment } from '@x402/axios';
import { ExactEvmScheme } from '@x402/evm';
import { privateKeyToAccount } from 'viem/accounts';

// Needs USDC on Base mainnet (no ETH needed — facilitator pays gas)
const payer = privateKeyToAccount(process.env.PAYER_KEY);
const client = new x402Client().register('eip155:*', new ExactEvmScheme(payer));
const api = wrapAxiosWithPayment(
  axios.create({ baseURL: 'https://webcap.shoutsid.fyi' }),
  client,
);

// Capture a screenshot (auto: unpaid → 402 → sign → retry)
const { data } = await api.post('/v1/x402/capture', { url: 'https://example.com', format: 'png' });
console.log(data.artifact.url);  // persistent public screenshot link

Python

import os
from x402 import X402Client
from x402.schemes import ExactEvmScheme
from eth_account import Account

payer = Account.from_key(os.environ["PAYER_KEY"])
client = X402Client().register("eip155:*", ExactEvmScheme(payer))

response = client.post(
    "https://webcap.shoutsid.fyi/v1/x402/capture",
    json={"url": "https://example.com", "format": "png"},
)
print(response.json()["artifact"]["url"])  # persistent public screenshot link

提取结构化数据

# Single URL
curl -s -X POST "https://webcap.shoutsid.fyi/v1/x402/extract" \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com"}'

# Batch (up to 50 URLs, one payment covers the whole batch)
curl -s -X POST "https://webcap.shoutsid.fyi/v1/x402/extract" \
  -H 'content-type: application/json' \
  -d '{"urls":["https://a.com","https://b.com"],"schema":"company name + tagline"}'

付款方式

当前使用的支付通道是加密货币（x402，Base 上的 USDC）——无需账户或 API 密钥。 银行卡付款是运营方可选的功能，并非托管功能：在运营方设置 STRIPE_SECRET_KEY 之前，POST /v1/stripe/checkout 会返回 stripe_not_configured，并指向加密货币支付通道。（目前，托管部署 https://webcap.shoutsid.fyi 不支持银行卡付款。）

银行卡付款（配置后使用 Stripe）

1. 使用套餐 ID 调用 POST /v1/stripe/checkout——后续流程由 Stripe Checkout 处理。
2. 输入银行卡信息。额度会立即添加到账户。
3. 后续调用使用 API 密钥进行身份验证。

加密货币支付（x402 — 无需账户）

webcap 使用 x402 v2——一种基于 HTTP 402、免 Gas 且无需账户的支付协议：

1. POST 请求收费路由且不提供付款信息 → HTTP 402 + 携带 base64 编码 x402 v2 挑战的 PAYMENT-REQUIRED 标头。
2. 读取 挑战信息：USDC 金额、商户地址、链信息。
3. 签名 免 Gas 的 EIP-3009 transferWithAuthorization（从你的钱包向商户转入指定金额）。无需 ETH——由支付中介提交交易并支付 Gas。
4. 在 PAYMENT-SIGNATURE 标头中附上已签名的载荷，重试 同一请求。支付中介会验证你的 USDC 余额，在链上结算并返回结果。

无需账户。无需 API 密钥。无需充值。只需 HTTP，以及你选择的支付方式。

自托管

# Clone the repo
git clone https://github.com/shoutsid-lab/webcap.git
cd webcap

# Install dependencies
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings

# Build and run
npm run build
npm start

从发行版 tarball 安装（无需 npm registry 账户）

打包好的 MCP 服务也作为 GitHub 发行版资源提供——像安装任何 npm 依赖项一样安装，无需发布到 npm：

# npm 12+ (Node 24) blocks remote tarball URLs by default — opt in explicitly:
npm install --allow-remote=all https://github.com/shoutsid-lab/webcap/releases/download/v0.1.0/shoutsid-webcap-0.1.0.tgz
# npm <= 11 accepts the URL without the flag:
npm install https://github.com/shoutsid-lab/webcap/releases/download/v0.1.0/shoutsid-webcap-0.1.0.tgz
npx webcap-mcp   # stdio MCP server

对于 MCP 宿主，无需安装的方式仍是首选：将其指向远程端点 https://webcap.shoutsid.fyi/mcp（streamable HTTP，无需安装软件包）。

Docker

docker compose build
docker compose up -d

Docker 配置包含运行状况检查、资源限制和持久化数据卷。详情请参阅 docker-compose.yml。

该技术栈还提供了公共边缘接入：cloudflared 服务运行 webcap Cloudflare 隧道，其入口配置位于 cloudflared/config.yml，凭据存放在 CF_TUNNEL_TOKEN（.env）中。应用不会向本机回环地址之外的网络发布，因此隧道容器是唯一的访问入口——如果没有它而运行 docker compose up -d，Cloudflare 会为 webcap.shoutsid.fyi 返回 530。

docker compose ps cloudflared                       # Up, not Restarting
docker compose logs --tail 20 cloudflared           # "Registered tunnel connection"
curl -s -o /dev/null -w '%{http_code}\n' https://webcap.shoutsid.fyi/v1/health   # 200

本地开发（Anvil 测试网）

npm install
npm run chain:up    # Starts Anvil with mintable USDC

WEBCAP_CHAIN=local \
WEBCAP_USDC_ADDRESS=$(jq -r .usdcContract /tmp/webcap-chain.json) \
WEBCAP_MERCHANT_ADDRESS=$(jq -r .merchant.address /tmp/webcap-chain.json) \
npm start

配置

所有环境变量均记录在 .env.example 中。重要变量如下：

变量	说明	默认值
WEBCAP_CHAIN	网络：base、base-sepolia 或 local	base-sepolia
WEBCAP_PUBLIC_BASE_URL	用于资源链接的公共 URL	必填
WEBCAP_X402_PRICE_USDC	每张截图的 USDC 价格	0.001
WEBCAP_X402_EXTRACT_PRICE_USDC	每次提取的 USDC 价格	0.01
X402_FACILITATOR_URL	支付中介端点	https://x402.org/facilitator

API 参考

完整的 OpenAPI 3.1 规范：GET /openapi.json

Agent 发现：GET /.well-known/x402、GET /v1/x402/service、GET /llms.txt、GET /skill.md

测试

npm test           # full vitest suite (tests/**/*.test.ts, no exclusions)
npm run typecheck  # Type checking

更改发布前，两项检查都必须通过。这里刻意不列测试或文件数量：这些数字已经两次过时（有读者在 issue #1 中发现了第二次），而无人重新生成的数字还不如不列。npm test 会输出当前统计结果。

声明审计

npm run audit:claims                                        # against localhost:8080
npm run audit:claims -- --base-url https://webcap.shoutsid.fyi  # against a deployment

测试检查代码；此项检查的是声明——它会读取 README.md、/skill.md 和 /llms.txt，验证其中公布的每个 METHOD /path 都确实提供服务、每个文档中记录的价格都与 402 挑战金额一致，而且免费服务页面描述的价格与收费路由相同。任何检查失败都会返回非零状态，因此可用于阻止部署。Issue #1 是由一个手动执行这项检查的 Agent 提交的；此命令执行的就是同一项检查。

许可证

MIT——详情请参阅 LICENSE。

链接

• 在线 API：https://webcap.shoutsid.fyi
• GitHub：https://github.com/shoutsid-lab/webcap
• OpenAPI 文档：https://webcap.shoutsid.fyi/openapi.json