Nanonets的DocStrange

文档提取API — 将PDF、图像和文档转换为markdown、JSON或CSV格式，并提供每个字段的置信度评分。

获取您的API密钥： https://docstrange.nanonets.com/app

快速开始

curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \
  -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \
  -F "file=@document.pdf" \
  -F "output_format=markdown"

响应：

{
  "success": true,
  "record_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "markdown": {
      "content": "# Invoice\n\n**Invoice Number:** INV-2024-001..."
    }
  }
}

设置

1. 获取您的API密钥

# Visit the dashboard
https://docstrange.nanonets.com/app

保存您的API密钥：

export DOCSTRANGE_API_KEY="your_api_key_here"

2. OpenClaw配置（可选）

推荐：使用环境变量（最安全）：

{
  skills: {
    entries: {
      "docstrange": {
        enabled: true,
        // API key loaded from environment variable DOCSTRANGE_API_KEY
      },
    },
  },
}

替代方案：存储在配置文件中（谨慎使用）：

{
  skills: {
    entries: {
      "docstrange": {
        enabled: true,
        env: {
          DOCSTRANGE_API_KEY: "your_api_key_here",
        },
      },
    },
  },
}

安全提示：如果要将API密钥存储在~/.openclaw/openclaw.json中：

• 设置文件权限：chmod 600 ~/.openclaw/openclaw.json
• 切勿将此文件提交到版本控制系统
• 尽可能使用环境变量或代理的秘密存储
• 定期轮换密钥，并在支持的情况下限制API密钥权限

常见任务

提取为Markdown

curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \
  -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \
  -F "file=@document.pdf" \
  -F "output_format=markdown"

访问内容：response["result"]["markdown"]["content"]

提取JSON字段

简单字段列表：

curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \
  -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "output_format=json" \
  -F 'json_options=["invoice_number", "date", "total_amount", "vendor"]' \
  -F "include_metadata=confidence_score"

使用JSON模式：

curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \
  -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "output_format=json" \
  -F 'json_options={"type": "object", "properties": {"invoice_number": {"type": "string"}, "total_amount": {"type": "number"}}}'

返回置信度分数：

{
  "result": {
    "json": {
      "content": {
        "invoice_number": "INV-2024-001",
        "total_amount": 500.00
      },
      "metadata": {
        "confidence_score": {
          "invoice_number": 98,
          "total_amount": 99
        }
      }
    }
  }
}

提取表格为CSV

curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \
  -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \
  -F "file=@table.pdf" \
  -F "output_format=csv" \
  -F "csv_options=table"

异步提取（大型文档）

对于超过5页的文档，使用异步并轮询：

将文档加入队列：

curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/async" \
  -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \
  -F "file=@large-document.pdf" \
  -F "output_format=markdown"

# Returns: {"record_id": "12345", "status": "processing"}

轮询结果：

curl -X GET "https://extraction-api.nanonets.com/api/v1/extract/results/12345" \
  -H "Authorization: Bearer $DOCSTRANGE_API_KEY"

# Returns: {"status": "completed", "result": {...}}

高级功能

边界框

获取元素坐标以进行布局分析：

-F "include_metadata=bounding_boxes"

层级输出

提取文档结构（章节、表格、键值对）：

-F "json_options=hierarchy_output"

财务文档模式

增强表格和数字格式化：

-F "markdown_options=financial-docs"

自定义指令

通过提示词引导提取：

-F "custom_instructions=Focus on financial data. Ignore headers."
-F "prompt_mode=append"

多种格式

单次调用请求多种格式：

-F "output_format=markdown,json"

使用场景

DocStrange 适用于：

• 发票和收据处理
• 合同文本提取
• 银行对账单解析
• 表单数字化
• 图像OCR（扫描文档）

不适用于：

• 超过5页的文档（请使用异步处理）
• 视频/音频转录
• 非文档类图像

最佳实践

JSON 提取：

• 字段列表：["字段1", "字段2"]— 快速提取
• JSON 模式：{"type": "object", ...}— 严格类型，嵌套数据

置信度分数：

• 添加include_metadata=confidence_score
• 每个字段的分数为 0-100
• 手动审查分数 <80 的字段

模式模板

发票

{
  "type": "object",
  "properties": {
    "invoice_number": {"type": "string"},
    "date": {"type": "string"},
    "vendor": {"type": "string"},
    "total": {"type": "number"},
    "line_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {"type": "string"},
          "quantity": {"type": "number"},
          "price": {"type": "number"}
        }
      }
    }
  }
}

收据

{
  "type": "object",
  "properties": {
    "merchant": {"type": "string"},
    "date": {"type": "string"},
    "total": {"type": "number"},
    "items": {
      "type": "array",
      "items": {"type": "object", "properties": {"name": {"type": "string"}, "price": {"type": "number"}}}
    }
  }
}

安全与隐私

数据处理

重要提示：上传到 DocStrange 的文档会传输至https://extraction-api.nanonets.com并在外部服务器上进行处理。

在上传敏感文件前：

• 查阅Nanonets的隐私政策和数据保留政策：https://docstrange.nanonets.com/docs
• 验证传输中（HTTPS）和静态数据的加密情况
• 确认数据删除/保留的时间线
• 先使用非敏感样本文件进行测试

最佳实践：

• 在确认服务的安全性和合规性状况之前，请勿上传高度敏感的个人身份信息（如社会安全号码、医疗记录、金融账户号码）
• 如有可能，请使用权限/范围受限的API密钥
• 定期轮换API密钥（建议每90天）
• 监控API使用日志以防未经授权的访问
• 切勿将API密钥记录或提交到代码仓库或示例中

文件大小限制

• 同步端点：建议用于≤5页的文件
• 异步端点：用于>5页的文件，以避免超时
• 大型文件：请考虑使用file_url使用可公开访问的URL，而不是直接上传大文件

操作安全措施

• 始终使用环境变量或安全的密钥存储库来存储API密钥
• 切勿在代码示例或文档中包含真实的API密钥
• 在示例中使用占位符值，例如"your_api_key_here"在示例中
• 在配置文件上设置适当的文件权限（JSON配置文件为600）
• 启用API密钥轮换并通过仪表板监控使用情况

故障排除

400 错误请求：

• 请准确提供一个输入：文件、file_url或file_base64
• 验证API密钥是否有效

同步超时：

• 对于超过5页的文档，请使用异步处理
• 轮询/extract/results/{record_id}

缺失置信度分数：

• 要求json_options（字段列表或模式）
• 添加include_metadata=confidence_score

身份验证错误：

• 验证DOCSTRANGE_API_KEY环境变量是否已设置
• 检查API密钥是否已过期或已被撤销
• 确保API密钥值中无多余空格

发布前安全检查清单

在发布或更新此技能前，请验证：

• package.json已声明requiredEnv和primaryEnv针对DOCSTRANGE_API_KEY
• package.json列出了API端点于端点数组
• 所有代码示例均使用占位值（"your_api_key_here"），而非真实的密钥
• SKILL.md或package.json文件中均未嵌入任何API密钥或机密信息
• 安全与隐私部分记录了数据处理方式及相关风险
• 配置示例包含针对明文存储的安全警告
• 配置文件包含文件权限指导

参考文档

• API文档： https://docstrange.nanonets.com/docs
• 获取API密钥： https://docstrange.nanonets.com/app
• 隐私政策： https://docstrange.nanonets.com/docs（请查找隐私/数据政策链接）