EasyLink EasyDoc Extract

Overview

Use this skill to call the EasyLink async extraction API and return structured field data from documents. Always follow the same lifecycle: validate inputs, submit task, poll result, present extracted fields.

Onboarding

If user has no API key, guide first:

1. Open https://platform.easylink-ai.com
2. Register or sign in
3. Enter API key management page and create a key
4. Store as EASYLINK_API_KEY

Platform

Single platform only (CN/EasyLink):

• Base URL: https://api.easylink-ai.com
• Submit: POST /v1/easydoc/extract
• Poll: GET /v1/easydoc/extract/{task_id}
• File form field: files

Modes

easydoc-extract has three behaviors based on parameters:

• json_schema provided → closed extraction (schema fields only)
• No schema, prompt_cus provided → prompt-driven extraction
• Neither provided → open extraction (auto-detects all key-value pairs)

Workflow

1. Validate request inputs

   • Require api-key from user input or EASYLINK_API_KEY env var.
   • Require at least one file. Validate extension against supported list.
   • Validate file size (<= 100MB).
   • Validate mode/schema/prompt combination (see Modes table).
   • If key is missing, return onboarding steps.

2. Submit async extraction task

   • POST multipart/form-data with files, mode, and optional json_schema or prompt_cus.
   • Read task_id from response.

3. Poll task status

   • GET /v1/easydoc/extract/{task_id} until terminal status.
   • Terminal: SUCCESS, ERROR, FAILED, COMPLETED, DONE
   • In-progress: PENDING, PROCESSING, RUNNING, IN_PROGRESS, QUEUED
   • Stop on terminal or timeout.

4. Normalize output

   • Keep raw response as raw.
   • Return stable envelope: task_id, status, results.
   • Each result entry contains page_number and fields (flat key→value map).

5. Handle failures predictably

   • Include task_id in error reports when available.
   • Report HTTP status and response body for API errors.
   • For failures, suggest checking file format or re-submission.

json_schema Format (universal modes only)

{
  "type": "object",
  "properties": {
    "字段名": { "type": "string" }
  }
}

Quick Commands

Open extraction (auto-detect all fields):

curl -X POST "https://api.easylink-ai.com/v1/easydoc/extract" \
  -H "api-key: $EASYLINK_API_KEY" \
  -F "files=@doc.pdf" \
  -F "mode=easydoc-extract"

Closed extraction with custom fields:

curl -X POST "https://api.easylink-ai.com/v1/easydoc/extract" \
  -H "api-key: $EASYLINK_API_KEY" \
  -F "files=@doc.pdf" \
  -F "mode=easydoc-extract" \
  -F 'json_schema={"type":"object","properties":{"姓名":{"type":"string"},"金额":{"type":"string"}}}'

Business license:

curl -X POST "https://api.easylink-ai.com/v1/easydoc/extract" \
  -H "api-key: $EASYLINK_API_KEY" \
  -F "files=@license.jpg" \
  -F "mode=bl-extract"

Org-code certificate:

curl -X POST "https://api.easylink-ai.com/v1/easydoc/extract" \
  -H "api-key: $EASYLINK_API_KEY" \
  -F "files=@cert.jpg" \
  -F "mode=occ-extract"

Poll status:

curl -X GET "https://api.easylink-ai.com/v1/easydoc/extract/{task_id}" \
  -H "api-key: $EASYLINK_API_KEY"

Bundled Python helper:

# Open extraction
python3 scripts/easydoc_extract.py --file ./doc.pdf --mode easydoc-extract

# Closed extraction with custom fields
python3 scripts/easydoc_extract.py --file ./doc.pdf --mode easydoc-extract \
  --fields "姓名" "日期" "金额" --save ./result.json

# Flash mode (returns bounding boxes, requires --fields)
python3 scripts/easydoc_extract.py --file ./doc.pdf --mode easydoc-extract-flash \
  --fields "姓名" "金额"

# Custom prompt
python3 scripts/easydoc_extract.py --file ./doc.pdf --mode easydoc-extract \
  --prompt "提取所有金额和日期"

# Business license
python3 scripts/easydoc_extract.py --file ./license.jpg --mode bl-extract

# Org-code certificate
python3 scripts/easydoc_extract.py --file ./cert.jpg --mode occ-extract

# Poll existing task only
python3 scripts/easydoc_extract.py --poll-only --task-id "b_extract_xxx"

References And Scripts

• Read references/easydoc-extract-api.md for endpoint details and error codes.
• Use scripts/easydoc_extract.py for deterministic submit and polling.
• Script default output is normalized; use --output-format raw for raw payload.

Output Contract

{
  "task_id": "string",
  "status": "SUCCESS|ERROR|PENDING|PROCESSING|FAILED|COMPLETED|DONE",
  "results": [
    {
      "page_number": 1,
      "fields": {
        "field_name": "value"
      }
    }
  ],
  "raw": {}
}