laiye-doc-processing

# Laiye Agentic Document Processing (ADP) Agentic Document Processing API — convert 10+ file formats（.jpeg,.jpg,.png,.bmp,.tiff,.pdf,.doc,.docx,.xls,.xlsx） to structured JSON/Excel with per-field confidence scores using VLM and LLM. > **Base URL:** `https://adp-global.laiye.com/?utm_source=github` ## Quick Start ```bash curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract" \ -H "Content-Type: application/json" \ -H "X-Access-Key: $ADP_ACCESS_KEY" \ -H "X-Timestamp: $(date +%s)" \ -H "X-Signature: $(uuidgen)" \ -d '{ "app_key": "$ADP_APP_KEY", "app_secret": "$ADP_APP_SECRET", "file_url": "https://example.com/invoice.pdf" }' ``` Response: ```json { "status": "success", "extraction_result": [ { "field_key": "invoice_number", "field_value": "INV-2024-001", "field_type": "text", "confidence": 0.95, "source_pages": [1] }, { "field_key": "total_amount", "field_value": "1000.00", "field_type": "number", "confidence": 0.98, "source_pages": [1] } ] } ``` ## Setup ### 1. Get Your API Credentials ```bash # Contact ADP service provider to obtain: # - app_key: Application access key # - app_secret: Application secret key # - X-Access-Key: Tenant-level access key ``` Save your credentials: ```bash export ADP_ACCESS_KEY="your_access_key_here" export ADP_APP_KEY="your_app_key_here" export ADP_APP_SECRET="your_app_secret_here" ``` ### 2. Configuration (Optional) **Recommended: Use environment variables** (most secure): ```json5 { skills: { entries: { "adp-doc-extraction": { enabled: true, // API credentials loaded from environment variables }, }, }, } ``` **Security Note:** - Set file permissions: `chmod 600 ~/.openclaw/openclaw.json` - Never commit this file to version control - Prefer environment variables or secret stores - Rotate credentials regularly ## Common Tasks ### Extract from File URL ```bash curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract" \ -H "Content-Type: application/json" \ -H "X-Access-Key: $ADP_ACCESS_KEY" \ -H "X-Timestamp: $(date +%s)" \ -H "X-Signature: $(uuidgen)" \ -d '{ "app_key": "'"$ADP_APP_KEY"'", "app_secret": "'"$ADP_APP_SECRET"'", "file_url": "https://example.com/document.pdf" }' ``` ### Extract from Base64 ```bash # Convert file to base64 file_base64=$(base64 -i document.pdf | tr -d '\n') curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract" \ -H "Content-Type: application/json" \ -H "X-Access-Key: $ADP_ACCESS_KEY" \ -H "X-Timestamp: $(date +%s)" \ -H "X-Signature: $(uuidgen)" \ -d "{ \"app_key\": \"$ADP_APP_KEY\", \"app_secret\": \"$ADP_APP_SECRET\", \"file_base64\": \"$file_base64\", \"file_name\": \"document.pdf\" }" ``` ### Extract with VLM Results ```bash curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract" \ -H "Content-Type: application/json" \ -H "X-Access-Key: $ADP_ACCESS_KEY" \ -H "X-Timestamp: $(date +%s)" \ -H "X-Signature: $(uuidgen)" \ -d '{ "app_key": "'"$ADP_APP_KEY"'", "app_secret": "'"$ADP_APP_SECRET"'", "file_url": "https://example.com/document.pdf", "with_rec_result": true }' ``` Access VLM results: `response["doc_recognize_result"]` ### Async Extraction (Large Documents) **Create extraction task:** ```bash curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract/create/task" \ -H "Content-Type: application/json" \ -H "X-Access-Key: $ADP_ACCESS_KEY" \ -H "X-Timestamp: $(date +%s)" \ -H "X-Signature: $(uuidgen)" \ -d '{ "app_key": "'"$ADP_APP_KEY"'", "app_secret": "'"$ADP_APP_SECRET"'", "file_url": "https://example.com/large-document.pdf" }' # Returns: {"task_id": "task_id_value", "metadata": {...}} ``` **Poll for results:** ```bash curl -X GET "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/extract/query/task/{task_id}" \ -H "X-Access-Key: $ADP_ACCESS_KEY" ``` ## Advanced Features ### Custom Scale Parameter Enhance VLM quality with higher resolution: ```bash # model_params: { "scale": 2.0 } ``` ### Specify Config Version Use a specific extraction configuration: ```bash # model_params: { "version_id": "config_version_id" } ``` ### Document Recognition Only Get VLM results without extraction: ```bash curl -X POST "https://adp-global.laiye.com/open/agentic_doc_processor/laiye/v1/app/doc/recognize" \ -H "Content-Type: application/json" \ -H "X-Access-Key: $ADP_ACCESS_KEY" \ -H "X-Timestamp: $(date +%s)" \ -H "X-Signature: $(uuidgen)" \ -d '{ "app_key": "'"$ADP_APP_KEY"'", "app_secret": "'"$ADP_APP_SECRET"'", "file_url": "https://example.com/document.pdf" }' ``` ## When to Use ### Use ADP For: - Invoice processing - Order processing - Receipt processing - Financial document processing - Logistics document processing - Multi-table document data extraction ### Don't Use For: - Video transcription - audio transcription ## Best Practices | Document Size | Endpoint | Notes | |---------------|----------|-------| | Small files | `/doc/extract` (sync) | Immediate response | | Large files | `/doc/extract/create/task` (async) | Poll for results | **File Input:** - `file_url`: Prefer for large files (already hosted) - `file_base64`: Use for direct upload (max 20MB) **Confidence Scores:** - Range: 0-1 per field - Review fields with confidence <0.8 manually **Response Structure:** - `extraction_result`: Array of extracted fields - `doc_recognize_result`: VLM results (when `with_rec_result=true`) - `metadata`: Processing info (pages, time, model) ## Response Schema ### Success Response ```json { "status": "success", "message": "string", "extraction_result": [ { "field_key": "string", "field_value": "string", "field_type": "text|number|date|table", "confidence": 0.95, "source_pages": [1], "table_data": [...] // for field_type="table" } ], "doc_recognize_result": [...], // when with_rec_result=true "extract_config_version": "string", "metadata": { "total_pages": 5, "processing_time": 8.2, "model_used": "gpt-4o" } } ``` ### Error Response ```json { "detail": "Error message description" } ``` ## Common Use Cases ### Invoice/Receipt Extraction Extracts: invoice_number, invoice_date, vendor/customer_name, currency, vat_rate, total_amount_including_tax, total_amount_excluding_tax, line_items, etc. ### Purchase Order Extraction Extracts: order_number, order_date, buyer_name/seller_name, address, total_amount, line_items, etc. ## Security & Privacy ### Data Handling **Important:** Documents uploaded to ADP are transmitted to `https://adp-global.laiye.com/?utm_source=github` and processed on external servers. **Before uploading sensitive documents:** - Review ADP privacy policy and data retention policies - Verify encryption in transit (HTTPS) and at rest - Confirm data deletion/retention timelines - Test with non-sensitive sample documents first **Best practices:** - Do not upload highly sensitive PII until you've confirmed security posture - Use credentials with limited permissions if available - Rotate credentials regularly (every 90 days recommended) - Monitor API usage logs for unauthorized access - Never log or commit credentials to repositories ### File Size Limits - **Max file size:** 50MB - **Supported formats:** .jpeg, .jpg, .png, .bmp, .tiff, .pdf, .doc, .docx, .xls, .xlsx - **Concurrency limit:** Free users support 1 concurrent request, paid users support 2 concurrent requests - **Timeout:** 10 minutes for sync requests ### Operational Safeguards - Always use environment variables or secure secret stores for credentials - Never include real credentials in code examples or documentation - Use placeholder values like `"your_access_key_here"` in examples - Set appropriate file permissions on configuration files (600) - Enable credential rotation and monitor usage ## Billing | Processing Stage | Cost | |-----------------|------| | Document Parsing | 0.5 credits/page | | Purchase Order Extraction | 1.5 credits/page | | Invoice/Receipt Extraction | 1.5 credits/page | | Custom Extraction | 1 credit/page | **New users:** 100 free credits per month, no application restrictions. ## Troubleshooting | Error Code | Description | Common Causes & Solutions | |------------|-------------|---------------------------| | **400 Bad Request** | Invalid request parameters | • Missing `app_key` or `app_secret`<br>• Must provide exactly one input: `file_url` or `file_base64`<br>• Application has no published extraction config | | **401 Unauthorized** | Authentication failed | • Invalid `X-Access-Key`<br>• Incorrect timestamp format (use Unix timestamp)<br>• Invalid signature format (must be UUID) | | **404 Not Found** | Resource not found | • Application does not exist<br>• No published extraction config found for the application | | **500 Internal Server Error** | Server-side processing error | • Document conversion failed<br>• VLM recognition timeout<br>• LLM extraction failure | | **Sync Timeout** | Request processing timed out | • Large files should use async endpoint<br>• Poll `/query/task/{task_id}` for results | ## Pre-Publish Security Checklist Before publishing or updating this skill, verify: - [ ] `package.json` declares `requiredEnv` and `primaryEnv` for credentials - [ ] `package.json` lists API endpoints in `endpoints` array - [ ] All code examples use placeholder values not real credentials - [ ] No credentials or secrets are embedded in `SKILL.md` or `package.json` - [ ] Security & Privacy section documents data handling and risks - [ ] Configuration examples include security warnings for plaintext storage - [ ] File permission guidance is included for config files ## References - **API Base URL:** https://adp-global.laiye.com/ - **Flow Documentation:** [ADP Flow Index](../../refers/backend/flows/ADP-Flow-Index.md) - **Extraction Flow:** [Document Extraction Flow](../../refers/backend/flows/09-Doc-Extraction-Flow.md) - **Recognition Flow:** [Document Recognition Flow](../../refers/backend/flows/08-Doc-Recognition-Flow.md)