Document Parse (Asynchronous)

How it works

Users can submit an inference request for an image or a PDF document with up to 1000 pages using the asynchronous Inference request API in Document Parse. Upon receiving the request, the API immediately returns a Request ID. After the input file is transferred and validated, it is divided into batches of 10 pages each, and inference is performed on each batch. Users can check the status of each batch in real-time using the Inference Response API. The inference results of each batch can be downloaded using the provided download_url in the response. The results will be available for downloading for 30 days from the time of the request.

Available models

Alias	Model	Release date	Description
document-parse	document-parse-240910	2024-09-10	Support for Microsoft Word, Excel, and Powerpoint. Markdown output for tables and list items. Base64 encoding of extracted images for all requested layout categories.

Request examples

Inference request

Request

import requests
 
api_key = "UPSTAGE_API_KEY"
filename = "invoice.png"
 
url = "https://api.upstage.ai/v1/document-ai/async/document-parse"
headers = {"Authorization": f"Bearer {api_key}"}
files = {"document": open(filename, "rb")}
data = {"ocr": True}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Response

{
    "request_id": "e7b1b3b0-1b3b-4b3b-8b3b-1b3b3b3b3b3b"
}

Retrieve inference results

Request

import requests
 
api_key = "UPSTAGE_API_KEY"
 
url = "https://api.upstage.ai/v1/document-ai/requests/REQUEST_ID"
headers = {"Authorization": f"Bearer {api_key}"}
response = requests.get(url, headers=headers)
print(response.json())

Response

 
{
    "id": "e7b1b3b0-1b3b-4b3b-8b3b-1b3b3b3b3b3b",
    "status": "completed",
    "model": "document-parse",
    "failure_message": "",
    "total_pages": 28,
    "completed_pages": 28,
    "batches": [
        {
            "id": 0,
            "model": "document-parse-240910",
            "status": "completed",
            "failure_message": "",
            "download_url": "https://download-url",
            "start_page": 1,
            "end_page": 10,
            "requested_at": "2024-07-01T14:47:01.863880448Z",
            "updated_at": "2024-07-01T14:47:15.901662097Z"
        },
        {
            "id": 1,
            "model": "document-parse-240910",
            "status": "completed",
            "failure_message": "",
            "download_url": "https://download-url",
            "start_page": 11,
            "end_page": 20,
            "requested_at": "2024-07-01T14:47:01.863880448Z",
            "updated_at": "2024-07-01T14:47:13.59782266Z"
        },
        {
            "id": 2,
            "model": "document-parse-240910",
            "status": "completed",
            "failure_message": "",
            "download_url": "https://download-url",
            "start_page": 21,
            "end_page": 28,
            "requested_at": "2024-07-01T14:47:01.863880448Z",
            "updated_at": "2024-07-01T14:47:37.061016766Z"
        }
    ],
    "requested_at": "2024-07-01T14:47:01.863880448Z",
    "completed_at": "2024-07-01T14:47:43.023542045Z"
}

Inference History

Request

import requests
 
api_key = "UPSTAGE_API_KEY"
 
url = "https://api.upstage.ai/v1/document-ai/requests"
headers = {"Authorization": f"Bearer {api_key}"}
response = requests.get(url, headers=headers)
print(response.json())

Response

{
    "requests": [
        {
            "id": "e7b1b3b0-1b3b-4b3b-8b3b-1b3b3b3b3b3b",
            "status": "completed",
            "model": "document-parse",
            "requested_at": "2024-07-01T14:47:01.863880448Z",
            "completed_at": "2024-07-01T14:47:43.023542045Z"
        }
    ]
}

Error Handlings

In Document Parse Async APIs, errors can occur in three different scenarios: request errors, batch-inference errors, or failures to retrieve the request result.

Request error

This error occurs when the input document cannot be handled by the API or if there's an error during processing, such as image conversion or page split. In case of a request failure, instead of returning a request ID, the API returns an object with error code and message.

{ 
  code: xxx, # http status code
  message: "", # detail error message 
}

The table below shows the error message and code for typical error cases.

error message	http status code
invalid model name	400
no document in the request	400
uploaded document is too large. max allowed size is 50MB	413
unsupported document format	415

Batch inference error

Due to the engine dividing the input document into batches of 10 pages each, each batch may have a different status for model inference. As the input file has already been validated before inference, batch inference errors are most likely caused by internal server errors. When this occurs, the API response for retrieving the result will show a failed status in the batches field with a failure_message.

Below code block shows the schema of batches field in the API response for inference result.

"batches": { 
  "id": number; 
  "model": string; 
  "status": scheduled | started | completed | failed | retrying;
  "failure_message": string; 
  "download_url": string;
  "start_page": number; 
  "end_page": number; 
  "requested_at": date; 
  "updated_at": date;
}[]

Failures to retrieve the request result

Normally, this error can occur when the download_url for each batch fails to generate. Due to security reasons, the download URL is only valid for 15 minutes and a new one is generated every time the user retrieves the inference result. When a user submits a long document, the server needs to create a download URL for each batch, and sometimes the server may struggle to create a high number of pre-signed URLs.

On this page