前提條件

• 獲取身份鑒權信息

  通過API調用AI搜索開放平臺服務時，需要對調用者身份進行鑒權，如何獲取鑒權信息請參見獲取API-KEY。

• 獲取服務調用地址

  支持通過公網和VPC兩種方式調用服務，詳情請參見獲取服務接入地址。

公共說明

• 請求body最大不能超過8MB。

概述

文檔內容解析提供了同步、異步兩類接口。同步接口因存在HTTP超時風險，不建議生產環境中使用，可用于調試接口。生產環境建議使用異步接口，共分為兩步，首先通過創建異步提取任務拿到task_id，然后調用獲取異步任務接口不斷查詢狀態直至任務完成。

創建異步提取任務

請求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-analyze/{service_id}/async

• host：調用服務的地址，支持通過公網和VPC兩種方式調用API服務，可參見獲取服務接入地址。

  

• workspace_name：工作空間名稱，例如default。

• service_id： 系統內置服務id，例如ops-document-analyze-001。

請求參數

Header參數

API-KEY認證

Body參數

如下圖中的文檔目錄與正文沒有明顯區分，在開啟該功能后，返回結果中層級結構更加準確。

• 未開啟語義結果提取功能：

  

• 開啟語義結果提取功能后，可以看到開啟后返回的結果層級結構更加準確（截圖中的“##”表示識別出的二級目錄）。

  

  說明

  usage.semantic_token_count有返回值表示語義結構提取成功，則收取此計費項產生的Token費用，若無返回值則表示語義提取未成功，則不涉及此計費項。

您可參照以下表格預估開啟語義結果提取后的用時及產生的語義Token數。

返回參數

Curl請求示例

curl --location 'http://****shanghai.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/async/' \
--header 'Authorization: Bearer 您的API Key' \
--header 'Content-Type: application/json' \
--data '{  
  "document":{
      "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241018/jahnyn/%E8%A7%A3%E6%9E%90%E6%B5%8B%E8%AF%95.doc"
    },
    "output" :{
      "image_storage":"base64"
    },
    "strategy": {
      "enable_semantic":true
    }
}'

響應示例

正常響應示例

{
    "request_id": "D5A4019E-853A-4E20-****-8053D9F5A9FC",
    "latency": 5.0,
    "http_code": 200,
    "result": {
        "task_id": "d5a4019e-853a-****-b5b6-8053d9f5a9fc"
    }
}

異常響應示例

在訪問請求出錯的情況下，輸出的結果中會通過code和message指明出錯原因。

{
    "request_id": "590A7EB8-AA84-****-AF31-8C35DC965972",
    "latency": 0.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "document.file_name required"
}

獲取異步提取任務

請求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-analyze/{service_id}/async/task-status?task_id=${task_id}

• host：調用服務的地址，支持通過公網和VPC兩種方式調用API服務，可參見獲取服務接入地址。

• workspace_name：工作空間名稱，例如default。

• service_id： 系統內置服務id，例如ops-document-analyze-001。

• task_id：創建文檔解析響應中返回的異步任務 ID，例如d5a4019e-853a-****-b5b6-8053d9f5a9fc。

請求參數

Header參數

API-KEY認證

返回參數

Curl請求示例

curl -XGET -H"Content-Type: application/json" 
"http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/async/task-status?task_id=110d6349-2e51-****-8bfb-25e5de434686" 
-H "Authorization: Bearer 您的API-KEY"

響應示例

正常響應示例

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B680492",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "Provided proper attribution is provided, Alibaba hereby grants permission to reproduce the tables and figures in this paper solely for use in journalistic or scholarly works....",
            "content_type": "markdown",
            "page_num": 15
        },
        "task_id": "24c3ad59-b196-****-974b-b63d63e05895"
    },
    "usage": {
        "token_count": 31867,
        "table_count": 4,
        "image_count": 8,
        "semantic_token_count":3068
    }
}

異常響應示例

在訪問請求出錯的情況下，輸出的結果中會通過code和message指明出錯原因。

{
    "request_id": "0F94BD89-989C-****-963C-6E4F3FF99445",
    "latency": 3.0,
    "code": "BadRequest.TaskNotExist",
    "http_code": 404,
    "message": "task[2fda34f5-40b4-****-a9a2-3e2c1e807361] not exist"
}

創建同步提取任務

請求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-analyze/{service_id}/sync

參數說明

• host：調用服務的地址，支持通過公網和VPC兩種方式調用API服務，可參見獲取服務接入地址。

• workspace_name：工作空間名稱，例如default。

• service_id： 系統內置服務id，例如ops-document-analyze-001。

請求參數

Header參數

API-KEY認證

Body參數

返回參數

Curl請求示例

curl --location 'http://****shanghai.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-analyze/ops-document-analyze-001/sync/' \
--header 'Authorization: Bearer 您的API Key' \
--header 'Content-Type: application/json' \
--data '{  
  "document":{
      "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241018/jahnyn/%E8%A7%A3%E6%9E%90%E6%B5%8B%E8%AF%95.doc"
    },
    "output" :{
      "image_storage":"base64"
    },
    "strategy": {
      "enable_semantic":true
    }
}'

響應示例

正常響應示例

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B689D04",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "Provided proper attribution is provided, Alibaba hereby grants permission to reproduce the tables and figures in this paper solely for use in journalistic or scholarly works....",
            "content_type": "markdown",
            "page_num": 15
        }
    },
    "usage": {
        "token_count": 31867,
        "table_count": 4,
        "image_count": 8,
        "semantic_token_count":3068
    }
}

異常響應示例

在訪問請求出錯的情況下，輸出的結果中會通過code和message指明出錯原因。

{
    "request_id": "6F33AFB6-A35C-****-AFD2-9EA16CCF4383",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\"
}

狀態碼說明

更多狀態碼說明，請參見狀態碼說明。