hyperbots-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HyperAPI Skill

HyperAPI 技能

This skill provides access to HyperAPI, a financial document intelligence platform with four core endpoints for processing invoices, receipts, and financial documents.

本技能可对接HyperAPI——一个金融文档智能平台，提供四个核心接口用于处理发票、收据及各类金融文档。

Capabilities

功能特性

HyperAPI provides four document intelligence endpoints:

Endpoint	Task	Use Case	Cost	Latency
`/v1/parse`	OCR Text Extraction	Extract raw text from any document	$0.05/page	~1s
`/v1/extract`	Structured Data Extraction	Get entities and line items from invoices	$0.08/page	~2s
`/v1/classify`	Document Classification	Categorize documents automatically	$0.03/page	~0.8s
`/v1/split`	PDF Segmentation	Split multi-document PDFs logically	$0.02/page	~0.5s

HyperAPI提供四个文档智能接口：

接口	任务	使用场景	成本	延迟
`/v1/parse`	OCR文本提取	从任意文档中提取原始文本	$0.05/页	~1秒
`/v1/extract`	结构化数据提取	从发票中提取实体信息和明细项	$0.08/页	~2秒
`/v1/classify`	文档分类	自动对文档进行分类	$0.03/页	~0.8秒
`/v1/split`	PDF拆分	逻辑拆分包含多文档的PDF	$0.02/页	~0.5秒

Base URL

基础URL

https://api.hyperapi.dev

https://api.hyperapi.dev

Authentication

身份验证

All API requests require an

X-API-Key

header:

Production keys:
```
hk_live_...
```
Test keys:
```
hk_test_...
```

Generate keys from your dashboard at https://hyperbots.com/dashboard

所有API请求均需携带

X-API-Key

请求头：

生产环境密钥：
```
hk_live_...
```
测试环境密钥：
```
hk_test_...
```

可从您的控制台生成密钥：https://hyperbots.com/dashboard

Quick Start

快速开始

Installation

安装

bash

pip install hyperapi

bash

pip install hyperapi

Basic Usage

基础用法

python

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_your_key_here")

python

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_your_key_here")

Parse - extract OCR text

解析 - 提取OCR文本

result = client.parse("document.pdf") print(result["result"]["ocr"])

Extract - get structured data

提取 - 获取结构化数据

result = client.extract("invoice.pdf") print(result["result"]["entities"]) print(result["result"]["line_items"])

client.close()

undefined

result = client.extract("invoice.pdf") print(result["result"]["entities"]) print(result["result"]["line_items"])

client.close()

undefined

API Reference

API参考

Parse Endpoint

解析接口

Extract raw text from documents using OCR.

Request:

bash

curl -X POST https://api.hyperapi.dev/v1/parse \
  -H "X-API-Key: hk_live_..." \
  -F "file=@document.pdf"

Response:

json

{
  "status": "success",
  "request_id": "req_01j9x...",
  "task": "parse",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "ocr": "Invoice\n\nBill To: Acme Corp\nDate: 2024-01-15..."
  },
  "duration_ms": 843,
  "metadata": {
    "pages": 2,
    "file_type": "pdf"
  }
}

通过OCR从文档中提取原始文本。

请求示例：

bash

curl -X POST https://api.hyperapi.dev/v1/parse \
  -H "X-API-Key: hk_live_..." \
  -F "file=@document.pdf"

响应示例：

json

{
  "status": "success",
  "request_id": "req_01j9x...",
  "task": "parse",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "ocr": "Invoice\n\nBill To: Acme Corp\nDate: 2024-01-15..."
  },
  "duration_ms": 843,
  "metadata": {
    "pages": 2,
    "file_type": "pdf"
  }
}

Extract Endpoint

提取接口

Extract structured entities and line items from documents.

Request:

bash

curl -X POST https://api.hyperapi.dev/v1/extract \
  -H "X-API-Key: hk_live_..." \
  -F "file=@invoice.pdf"

Response:

json

{
  "status": "success",
  "request_id": "req_01ja0...",
  "task": "extract",
  "model_used": "hyperbots_vlm_extract",
  "result": {
    "entities": {
      "invoice_number": "INV-2024-0042",
      "date": "2024-01-15",
      "due_date": "2024-02-15",
      "vendor_name": "Acme Supplies Ltd",
      "total_amount": "1,250.00",
      "currency": "USD"
    },
    "line_items": [
      {
        "description": "Widget A",
        "quantity": 10,
        "unit_price": "100.00",
        "total": "1,000.00"
      }
    ]
  },
  "duration_ms": 1820,
  "metadata": { "pages": 2 }
}

从文档中提取结构化实体和明细项。

请求示例：

bash

curl -X POST https://api.hyperapi.dev/v1/extract \
  -H "X-API-Key: hk_live_..." \
  -F "file=@invoice.pdf"

响应示例：

json

{
  "status": "success",
  "request_id": "req_01ja0...",
  "task": "extract",
  "model_used": "hyperbots_vlm_extract",
  "result": {
    "entities": {
      "invoice_number": "INV-2024-0042",
      "date": "2024-01-15",
      "due_date": "2024-02-15",
      "vendor_name": "Acme Supplies Ltd",
      "total_amount": "1,250.00",
      "currency": "USD"
    },
    "line_items": [
      {
        "description": "Widget A",
        "quantity": 10,
        "unit_price": "100.00",
        "total": "1,000.00"
      }
    ]
  },
  "duration_ms": 1820,
  "metadata": { "pages": 2 }
}

Classify Endpoint

分类接口

Categorize documents into financial document types.

Request:

bash

curl -X POST https://api.hyperapi.dev/v1/classify \
  -H "X-API-Key: hk_live_..." \
  -F "file=@document.pdf"

Response:

json

{
  "status": "success",
  "request_id": "req_01j9y...",
  "task": "classify",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "label": "invoice",
    "confidence": 0.98,
    "candidates": [
      { "label": "invoice", "confidence": 0.98 },
      { "label": "receipt", "confidence": 0.01 },
      { "label": "contract", "confidence": 0.01 }
    ]
  },
  "duration_ms": 612,
  "metadata": { "pages": 1 }
}

将文档归类为金融文档类型。

请求示例：

bash

curl -X POST https://api.hyperapi.dev/v1/classify \
  -H "X-API-Key: hk_live_..." \
  -F "file=@document.pdf"

响应示例：

json

{
  "status": "success",
  "request_id": "req_01j9y...",
  "task": "classify",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "label": "invoice",
    "confidence": 0.98,
    "candidates": [
      { "label": "invoice", "confidence": 0.98 },
      { "label": "receipt", "confidence": 0.01 },
      { "label": "contract", "confidence": 0.01 }
    ]
  },
  "duration_ms": 612,
  "metadata": { "pages": 1 }
}

Split Endpoint

拆分接口

Segment multi-document PDFs into individual documents.

Request:

bash

curl -X POST https://api.hyperapi.dev/v1/split \
  -H "X-API-Key: hk_live_..." \
  -F "file=@batch.pdf"

Response:

json

{
  "status": "success",
  "request_id": "req_01j9z...",
  "task": "split",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "segments": [
      { "document_index": 0, "start_page": 1, "end_page": 3, "type": "invoice" },
      { "document_index": 1, "start_page": 4, "end_page": 5, "type": "receipt" }
    ]
  },
  "duration_ms": 490,
  "metadata": { "pages": 5 }
}

将包含多文档的PDF分割为单个文档。

请求示例：

bash

curl -X POST https://api.hyperapi.dev/v1/split \
  -H "X-API-Key: hk_live_..." \
  -F "file=@batch.pdf"

响应示例：

json

{
  "status": "success",
  "request_id": "req_01j9z...",
  "task": "split",
  "model_used": "hyperbots_vlm_ocr",
  "result": {
    "segments": [
      { "document_index": 0, "start_page": 1, "end_page": 3, "type": "invoice" },
      { "document_index": 1, "start_page": 4, "end_page": 5, "type": "receipt" }
    ]
  },
  "duration_ms": 490,
  "metadata": { "pages": 5 }
}

Error Handling

错误处理

All errors return a JSON body with an error object:

Status	Code	Description
401	Unauthorized	Missing or invalid X-API-Key
402	Payment Required	Insufficient credit balance
413	Payload Too Large	File exceeds 50 MB limit
422	Unprocessable Entity	Unsupported file type
429	Too Many Requests	Rate limit exceeded
503	Service Unavailable	Backend unavailable (circuit open)

Error Response:

json

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your credit balance is too low to process this request."
  }
}

所有错误均返回包含错误对象的JSON响应：

状态码	错误码	描述
401	Unauthorized	缺少或无效的X-API-Key
402	Payment Required	余额不足
413	Payload Too Large	文件大小超过50MB限制
422	Unprocessable Entity	不支持的文件类型
429	Too Many Requests	超过请求频率限制
503	Service Unavailable	后端服务不可用（熔断状态）

错误响应示例：

json

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your credit balance is too low to process this request."
  }
}

Rate Limits

请求频率限制

Rate limits are applied per API key, per minute:

Tier	Requests/min	Concurrency	Priority
Free	10	1	1
Pro	100	10	10
Enterprise	Unlimited	100	100

请求频率限制按每个API密钥、每分钟计算：

套餐	每分钟请求数	并发数	优先级
免费版	10	1	1
专业版	100	10	10
企业版	无限制	100	100

SDK Methods

SDK方法

Python SDK

python

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_...")

python

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_...")

All available methods

所有可用方法

client.parse(file_path) # OCR extraction client.extract(file_path) # Structured data extraction client.classify(file_path) # Document classification client.split(file_path) # PDF segmentation client.process(file_path) # Parse + Extract combined client.upload_document(file_path) # S3 presigned upload

client.close()

undefined

client.parse(file_path) # OCR提取 client.extract(file_path) # 结构化数据提取 client.classify(file_path) # 文档分类 client.split(file_path) # PDF拆分 client.process(file_path) # 解析+提取组合操作 client.upload_document(file_path) # S3预签名上传

client.close()

undefined

Node.js SDK

Coming soon.

即将推出。

Best Practices

最佳实践

Use Presigned Uploads: For files > 50 MB, use
```
client.upload_document()
```
which handles S3 presigned URL flow.
Choose the Right Endpoint:
- Need raw text? Use
```
parse
```
- Need structured data? Use
```
extract
```
- Need to categorize? Use
```
classify
```
- Have multi-doc PDFs? Use
```
split
```
Handle Rate Limits: Implement exponential backoff for 429 responses.
Verify File Types: Supported formats are PDF, PNG, and JPG.

使用预签名上传：对于大于50MB的文件，使用
```
client.upload_document()
```
方法，该方法可处理S3预签名URL流程。
选择合适的接口：
- 需要原始文本？使用
```
parse
```
  接口
- 需要结构化数据？使用
```
extract
```
  接口
- 需要分类？使用
```
classify
```
  接口
- 处理多文档PDF？使用
```
split
```
  接口
处理频率限制：针对429响应实现指数退避策略。
验证文件类型：支持的格式为PDF、PNG和JPG。

CLI Usage

CLI使用

A bundled CLI script is available:

bash

export HYPERAPI_KEY=hk_live_...
python3 scripts/hyperbots_cli.py extract invoice.pdf

See references/api_docs.md for complete documentation.

提供捆绑的CLI脚本：

bash

export HYPERAPI_KEY=hk_live_...
python3 scripts/hyperbots_cli.py extract invoice.pdf

完整文档请参见references/api_docs.md。