doc-extract-api

doc-extract-api

文档转结构化 JSON 提取 API。输入 PDF/PNG/JPEG，返回简洁的 JSON。 四种固定文档类型（发票、收据、合同、简历）会获得匹配的架构和领域专属验证；/extract/custom 则接受任意 JSON Schema，因此调用方不受这四种类型的限制。专为自主 AI Agent 打造：无需注册、无需 API 密钥，也无需人工结账——Agent 可通过 x402 v2（USDC）发现价格并按次付费，全程通过 HTTP 完成，还可以通过 x402 Bazaar 发现目录以编程方式找到此服务。此服务也以 MCP 服务的形式发布（npm 上的 doc-extract-api-mcp，以及官方 MCP Registry）——但它只是同一个付费 API 的客户端，并非免费替代方案：每次调用 MCP 工具，都会从你提供的钱包中实际支付 x402 款项，而不是在本地运行、不限量的提取服务。此服务没有免费使用方式。

为什么使用 x402，而不是 Stripe

Stripe Checkout 是为人类打造的——它通过 UI 收取银行卡信息，其支付按钮会主动阻止非受信任的程序化（由 Agent 驱动的）提交。x402 让 HTTP 402 Payment Required 状态码重获新生：访问付费端点但未付款时，会收到一个 402 响应，其 PAYMENT-REQUIRED 标头包含完整、机器可读的清单（价格、网络、收款地址、资产，以及通过 Bazaar 扩展提供的完整输入/输出架构和实际示例）。然后通过 X-PAYMENT 标头携带已签名的 USDC 转账授权并重试，请求即可通过。无需账户、无需密钥、无需人工介入——发现和支付步骤就是同一次 HTTP 往返。

只有在提取成功后，款项才会结算——@x402/hono 的中间件会在运行处理程序前验证支付签名，但只有当处理程序返回非错误状态时才会执行实际的链上转账（已确认：此项目的 paymentMiddlewareFromConfig 调用会在被包装的路由响应为 ≥400 时跳过结算）。提取失败不会让调用方产生任何费用。

发现：x402 Bazaar

Bazaar（GET {facilitator}/discovery/resources）是一个实时、可查询的 x402 服务目录——截至本文撰写时约有 15k 条目，可供 Agent 客户端搜索（client.extensions.bazaar.search({ query: "..." })）。要加入目录，无需填写提交表单：facilitator 会在首次处理回显了路由声明的 bazaar 扩展的实际付款时，自动为资源编目。src/lib/discovery.ts 为全部四个路由声明了该扩展，包含完整输入架构（multipart form-data，file 字段）和经验证的实际输出示例——因此，一旦某个路由收到首笔主网实时付款，它就会出现在目录中，并提供足够详细的信息，让 Agent 无需阅读任何文档即可正确集成。截至本文撰写时，/extract/invoice 的目录条目仍显示迁移前的旧记录，而非这些丰富内容——请查看 git 历史记录或询问状态；/extract/receipt、/extract/contract 和 /extract/resume 尚未收到主网付款，因此还未编入目录。

定位（基于撰写目录文案前对实时 Bazaar 的调查）：通用 OCR 竞品免费，但只返回未经验证的原始文本；通用结构化提取竞品每次调用收费约 $0.10，并要求调用方事先提供纯文本，而非原始文件。我们发现，只有此条目同时具备这两点——输入原始 PDF/图像，输出经过验证的固定架构。定价（见 wrangler.toml）按路由与该类别中直接竞品经验证的最低实时 402 价格匹配，而非单独设定——发票/收据/简历/自定义类型收费 $0.02，合同收费 $0.03（其真正可比的竞品价格高出一美分）。确切的目录文案和各路由的标签（serviceName/tags/description）请参见 src/lib/discovery.ts。

架构

• schemas/ — invoice、receipt、contract 和 resume 提取结果的 JSON Schema （同时也是发送给 Claude 的工具 input_schema，因此模型必须严格遵循此结构）。
• src/lib/claude.ts — 调用 Anthropic Messages API，将文档作为原生 document/image 内容块传入，并强制指定 tool_choice，因此模型只能返回符合该 Schema 的内容。
• src/lib/validate.ts — 提取后的合理性检查：行项目之和等于小计，小计 + 税额（+ 小费）≈ 总额，日期有效且未在未来，货币为真实的 ISO 4217 代码，并标记置信度较低的字段。
• src/lib/extract.ts — 编排一次提取流程并进行验证；若验证失败，则使用纠正提示重试一次，准确说明哪些数值对不上。绝不会静默失败：无论结果如何，都会在数据旁返回 validation_warnings。
• src/lib/customSchema.ts / src/routes/customExtractHandler.ts — /extract/custom： 使用相同的 Claude 强制工具调用引擎，但工具的 input_schema 是调用方在请求时提供的 JSON Schema，而不是四种固定 Schema 之一。这里没有特定领域的验证器（没有固定领域可供核对），因此返回的是符合 Schema 的输出，而非经过事实核查的输出——validation_warnings 始终为 []。调用方提供的 Schema 有边界限制（≤6000 个字符、深度 ≤4、每层 ≤30 个属性、不允许 $ref），不符合要求时会在调用模型之前以 400 响应拒绝——此操作不产生费用，因为 x402 只会在响应非错误时结算。请求可接受 file（二进制 PDF/图像，与固定路由相同）或 content（调用方已有的原始文本/HTML，例如已抓取的网页，≤100,000 个字符），两者必须且只能提供一个。发送给 Claude 的提示词会明确将文本/HTML 标记为数据而非指令，因为这是调用方任意提供的内容，否则可能成为提示注入途径。
• src/lib/facilitator.ts — 在测试网上选择免费的默认 facilitator；在主网上（X402_NETWORK = "base"）使用 Coinbase 经过身份验证的 CDP facilitator，以及 Mogami 和 PayAI，以扩展与 Bazaar 等效的发现覆盖面（CDP 仍排在首位/作为主要 facilitator——较早的 facilitator 在验证/结算时拥有优先权）；并将本项目的人类可读网络名称映射为 x402 v2 使用的 CAIP-2 标识符（eip155:8453 等）。重要：src/index.ts 在模块级别缓存构建好的支付中间件，而不是每个请求都重新构建——如果有多个 facilitator，其中一个运行异常时，会让 initialize() 增加其完整超时时间；每个请求都重新构建就意味着每次请求都要付出此代价（首次尝试多个 facilitator 时，这完全破坏了 API）。缓存后，只有冷启动隔离环境的第一个请求需要付出此代价。
• src/lib/discovery.ts — Bazaar 列表内容：四个路由的描述、标签和发现扩展（Schema + 真实示例）。
• src/index.ts — 运行于 Cloudflare Workers 的 Hono 应用。@x402/hono 的 paymentMiddlewareFromConfig 保护 /extract/*；它根据 Env 绑定按请求构建（Workers 只会在请求期间提供环境变量，而不会在模块加载时提供）。
• src/routes/extractHandler.ts — 纯提取逻辑；执行到这里时，支付已经过验证。
• mcp/server.ts — stdio MCP 服务，提供 extract_invoice、extract_receipt、 extract_contract、extract_resume 和 extract_custom 工具。每次工具调用都会通过 WALLET_PRIVATE_KEY 提供的钱包签署并发送真实的 x402 付款（使用 @x402/fetch 的 wrapFetchWithPayment，与 scripts/test-payment.mjs 使用相同机制），然后通过网络调用在线 HTTP API——它不会在本地执行提取，也不会直接调用 Claude。 没有免费调用途径：缺少钱包或钱包余额不足时，失败方式与直接调用 API 相同。

与原始规范的一处刻意偏离

规范假设了一个 PDF→图像转换步骤（pdf2image/poppler）。Cloudflare Workers 无法运行原生二进制文件，而 Claude 的 Messages API 原生接受 document 内容块中的 PDF，因此 PDF 会原样发送给 Claude。这样既移除了整个流水线阶段，也移除了一个无论如何都无法在 Workers 上运行的依赖。

设置

cd "doc-extract-api"
npm install

1. 密钥

本地开发 — 将 .dev.vars.example 复制为 .dev.vars，并填入真实密钥（已加入 gitignore）：

cp .dev.vars.example .dev.vars

生产环境：

npx wrangler secret put ANTHROPIC_API_KEY

2. 钱包 — 收款地址

编辑 wrangler.toml：在此服务能够接收实际付款之前，X402_PAY_TO_ADDRESS 必须设置为你控制的真实钱包地址。这是公开的收款地址（可以安全提交，类似银行账号）——切勿在此项目的任何位置放入私钥。

X402_NETWORK 默认值为 base-sepolia（测试网，可从水龙头领取免费的测试 USDC — 适合在完全没有真实资金风险的情况下验证整个流程）。

价格按路由单独设置，不共享：X402_INVOICE_PRICE、X402_RECEIPT_PRICE、X402_CONTRACT_PRICE、X402_RESUME_PRICE、X402_CUSTOM_PRICE。默认价格与各类别中已验证的最低现行竞品价格持平 — 参见上文的定位说明。

2b. 切换到主网（X402_NETWORK = "base"）

免费默认 Facilitator（x402.org/facilitator，在测试网上自动使用）仅支持测试网 — 主网需要经过身份验证的 Facilitator。本项目已接入 Coinbase 的 CDP Facilitator（src/lib/facilitator.ts）：

1. 创建一个 CDP Portal 账号，并在 Project → API Keys 下创建一个 Secret API Key。
2. npx wrangler secret put CDP_API_KEY_ID
3. npx wrangler secret put CDP_API_KEY_SECRET
4. 在 wrangler.toml 中设置 X402_NETWORK = "base"，然后重新部署。

价格：每月结算的前约 1,000 笔交易免费，之后每笔 $0.001 — 付款验证始终免费。如果 X402_NETWORK 为 "base"，但未设置这些密钥，请求会在 Facilitator 配置步骤明确报错，而不会静默地错误配置付款。

要在 Bazaar 上架，至少需要完成一笔真实的主网付款 — Facilitator 首次处理带有 bazaar 扩展的付款时，会将该资源加入目录。使用真实且已注资的钱包运行一次 scripts/test-payment.mjs 来触发此流程（见下文），然后通过以下命令确认：

curl -s "https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources?limit=200" \
  | grep -o 'doc-extract-api'

3. 端到端付款测试（scripts/test-payment.mjs）

模拟真实的自主 Agent：生成或使用一次性钱包，通过 x402 v2 付款，并调用线上 API。请先为测试钱包注资 — 可从水龙头领取测试网 USDC（例如，faucet.circle.com，Base Sepolia），免费运行；如果 X402_NETWORK 为 "base"，也可以在 Base 上使用少量真实 USDC：

node scripts/gen-test-wallet.mjs        # prints a fresh throwaway private key + address
TEST_WALLET_PRIVATE_KEY=0x... node scripts/test-payment.mjs

会打印结算详情以及收款方 USDC 余额的前后变化 — 已确认在 Base Sepolia（测试网）和使用真实 USDC 的 Base 主网上均可端到端运行。

4. 本地运行

npm run dev

curl -X POST http://localhost:8787/extract/invoice -F "file=@/path/to/invoice.pdf"
# → 402 Payment Required; full payment + discovery manifest in the PAYMENT-REQUIRED header

/extract/custom 接受一个 schema 字段（JSON Schema 字符串，type: "object"）、一个可选的 instructions 字段，以及 file（二进制）或 content（原始文本/HTML）两者中的且仅其中一个：

curl -X POST http://localhost:8787/extract/custom \
  -F "file=@/path/to/doc.pdf" \
  -F 'schema={"type":"object","properties":{"order_id":{"type":"string"},"ship_date":{"type":"string"}}}' \
  -F "instructions=Dates in YYYY-MM-DD"

也可以直接使用已有的原始文本/HTML — 无需文件：

curl -X POST http://localhost:8787/extract/custom \
  -F "content=<html><body><h1>Acme Corp</h1><p>Founded 1998, HQ in Austin, TX</p></body></html>" \
  -F 'schema={"type":"object","properties":{"company":{"type":"string"},"founded":{"type":"number"},"hq":{"type":"string"}}}'

实际调用方会使用支持 x402 的 HTTP 客户端（例如 Agent 端的 @x402/fetch），自动处理 402 → 签署付款 → 重试循环。

5. 部署

npm run deploy

6. MCP 服务（付费，供 Agent 使用）

export WALLET_PRIVATE_KEY=0x...   # a wallet funded with real USDC on Base — every call spends from it
npm run mcp

或者，发布后，MCP 客户端无需克隆此仓库即可直接运行：

npx doc-extract-api-mcp

将支持 MCP 的客户端指向此 stdio 服务，即可将 extract_invoice、extract_receipt、extract_contract、extract_resume 和 extract_custom 暴露为工具。每次调用都会通过 x402 在网络上调用线上 API 并付款 — 不存在本地/免费提取路径，客户端也完全不需要 ANTHROPIC_API_KEY（该密钥由服务端持有；调用方只需要一个已注资的钱包）。

尚未完成

• 简历包含真实的个人身份信息（姓名、联系方式、工作经历）。响应返回后不会保留任何数据（与此处的其他文档类型相同），但鉴于其敏感性，值得再次说明——请参阅 src/lib/discovery.ts 中的简历说明。