介绍
# DocStrange by Nanonets
文档提取 API — 将 PDF、图像和文档转换为 Markdown、JSON 或 CSV，并提供逐字段的置信度评分。
> **获取您的 API 密钥：** https://docstrange.nanonets.com/app
## 快速开始
```bash curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \ -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \ -F "[email protected]" \ -F "output_format=markdown" ```
响应： ```json { "success": true, "record_id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "result": { "markdown": { "content": "# Invoice\n\n**Invoice Number:** INV-2024-001..." } } } ```
## 设置
### 1. 获取您的 API 密钥
```bash # Visit the dashboard https://docstrange.nanonets.com/app ```
保存您的 API 密钥： ```bash export DOCSTRANGE_API_KEY="your_api_key_here" ```
### 2. OpenClaw 配置（可选）
**推荐：使用环境变量**（最安全）： ```json5 { skills: { entries: { "docstrange": { enabled: true, // API key loaded from environment variable DOCSTRANGE_API_KEY }, }, }, } ```
**备选方案：存储在配置文件中**（请谨慎使用）： ```json5 { skills: { entries: { "docstrange": { enabled: true, env: { DOCSTRANGE_API_KEY: "your_api_key_here", }, }, }, }, } ```
**安全提示：** 如果将 API 密钥存储在 `~/.openclaw/openclaw.json` 中： - 设置文件权限：`chmod 600 ~/.openclaw/openclaw.json` - 切勿将此文件提交到版本控制 - 尽可能优先使用环境变量或您代理的密钥存储 - 定期轮换密钥，如果支持，请限制 API 密钥权限
## 常见任务
### 提取为 Markdown
```bash curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \ -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \ -F "[email protected]" \ -F "output_format=markdown" ```
访问内容：`response["result"]["markdown"]["content"]`
### 提取 JSON 字段
**简单字段列表：** ```bash curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \ -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \ -F "[email protected]" \ -F "output_format=json" \ -F 'json_options=["invoice_number", "date", "total_amount", "vendor"]' \ -F "include_metadata=confidence_score" ```
**使用 JSON 架构：** ```bash curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \ -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \ -F "[email protected]" \ -F "output_format=json" \ -F 'json_options={"type": "object", "properties": {"invoice_number": {"type": "string"}, "total_amount": {"type": "number"}}}' ```
包含置信度评分的响应： ```json { "result": { "json": { "content": { "invoice_number": "INV-2024-001", "total_amount": 500.00 }, "metadata": { "confidence_score": { "invoice_number": 98, "total_amount": 99 } } } } } ```
### 提取表格为 CSV
```bash curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/sync" \ -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \ -F "[email protected]" \ -F "output_format=csv" \ -F "csv_options=table" ```
### 异步提取（大文档）
对于超过 5 页的文档，请使用异步模式并轮询：
**将文档加入队列：** ```bash curl -X POST "https://extraction-api.nanonets.com/api/v1/extract/async" \ -H "Authorization: Bearer $DOCSTRANGE_API_KEY" \ -F "[email protected]" \ -F "output_format=markdown"
# Returns: {"record_id": "12345", "status": "processing"} ```
**轮询结果：** ```bash curl -X GET "https://extraction-api.nanonets.com/api/v1/extract/results/12345" \ -H "Authorization: Bearer $DOCSTRANGE_API_KEY"
# Returns: {"status": "completed", "result": {...}} ```
## 高级功能
### 边界框 获取元素坐标以进行布局分析： ```bash -F "include_metadata=bounding_boxes" ```
### 层级输出 提取文档结构（章节、表格、键值对）： ```bash -F "json_options=hierarchy_output" ```
### 金融文档模式 增强的表格和数字格式： ```bash -F "markdown_options=financial-docs" ```
### 自定义指令 使用提示词引导提取： ```bash -F "custom_instructions=Focus on financial data. Ignore headers." -F "prompt_mode=append" ```
### 多种格式 在一次调用中请求多种格式： ```bash -F "output_format=markdown,json" ```
## 适用场景
### 适用于 DocStrange 的场景： - 发票和收据处理 - 合同文本提取 - 银行对账单解析 - 表单数字化 - 图像 OCR（扫描文档）
### 不适用的场景： - 超过 5 页且使用同步模式的文档（请使用异步模式） - 视频/音频转录 - 非文档类图像
## 最佳实践
| 文档大小 | 端点 | 备注 | |---------------|----------|-------| | <=5 页 | `/extract/sync` | 立即响应 | | >5 页 | `/extract/async` | 轮询结果 |
**JSON 提取：** - 字段列表：`["field1", "field2"]` — 快速提取 - JSON 架构：`{"type": "object", ...}` — 严格类型、嵌套数据
**置信度评分：** - 添加 `include_metadata=confidence_score` - 评分为每字段 0-100 分 - 人工审查分数低于 80 的字段
## 架构模板
### 发票 ```json { "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"} } } } } } ```
### 收据 ```json { "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）和静态数据的加密情况 - 确认数据删除/保留时间线 - 首先使用非敏感样本文档进行测试
**最佳实践：** - 在确认服务的安全性和合规性之前，请勿上传高度敏感的 PII（SSN、医疗记录、金融账号） - 如果可用，请使用权限/范围受限的 API 密钥 - 定期轮换 API 密钥（建议每 90 天） - 监控 API 使用日志以发现未经授权的访问 - 切勿将 API 密钥记录或提交到存储库或示例中
### 文件大小限制
- **同步端点：** 建议用于 ≤5 页的文档 - **异步端点：** 用于 >5 页的文档以避免超时 - **大文件：** 考虑使用带有公开可访问 URL 的 `file_url`，而不是直接上传大文件
### 操作保障
- 始终使用环境变量或安全的密钥存储来保存 API 密钥 - 切勿在代码示例或文档中包含真实的 API 密钥 - 在示例中使用占位符值，如 `"your_api_key_here"` - 为配置文件设置适当的文件权限（JSON 配置文件设为 600） - 启用 API 密钥轮换并通过仪表板监控使用情况
## 故障排除
**400 Bad Request：** - 仅提供一个输入：`file`、`file_url` 或 `file_base64` - 验证 API 密钥是否有效
**同步超时：** - 对于超过 5 页的文档，请使用异步模式 - 轮询 `/extract/results/{record_id}`
**缺少置信度评分：** - 需要配置 `json_options`（字段列表或架构） - 添加 `include_metadata=confidence_score`
**身份验证错误：** - 验证是否设置了 `DOCSTRANGE_API_KEY` 环境变量 - 检查 API 密钥是否过期或已被撤销 - 确保 API 密钥值中没有多余的空格
## 发布前安全检查清单
在发布或更新此技能之前，请验证：
- [ ] `package.json` 为 `DOCSTRANGE_API_KEY` 声明了 `requiredEnv` 和 `primaryEnv` - [ ] `package.json` 在 `endpoints` 数组中列出了 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（查看隐私/数据政策链接）