MinerU API Management

https://mineru.net/apiManage/docs
Admin
MinerU is a platform that provides state-of-the-art (SOTA) document parsing capabilities, accessible...
Tokens:13,701
Snippets:77
Trust Score:7.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Task Status Response Examples

Source: https://mineru.net/apiManage/docs

Example JSON responses for tasks currently in progress and tasks that have successfully completed.

```json
{
  "code": 0,
  "data": {
    "task_id": "47726b6e-46ca-4bb9-******",
    "state": "running",
    "err_msg": "",
    "extract_progress": {
      "extracted_pages": 1,
      "total_pages": 2,
      "start_time": "2025-01-20 11:43:20"
    }
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

```json
{
  "code": 0,
  "data": {
    "task_id": "47726b6e-46ca-4bb9-******",
    "state": "done",
    "full_zip_url": "https://cdn-mineru.openxlab.org.cn/pdf/018e53ad-d4f1-475d-b380-36bf24db9914.zip",
    "err_msg": ""
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### Batch URL Upload Request Example

Source: https://mineru.net/apiManage/docs

Example JSON body for initiating a batch extraction task with a file URL and model version.

```json
{
  "files": [
    {
      "url": "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
      "data_id": "abcd"
    }
  ],
  "model_version": "vlm"
}
```

--------------------------------

### Create Extract Task Response Example

Source: https://mineru.net/apiManage/docs

Example of a successful JSON response returned after initiating an extraction task.

```json
{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b4***"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### Batch URL Upload Response Example

Source: https://mineru.net/apiManage/docs

Example JSON response returned upon successful submission of a batch extraction task.

```json
{
  "code": 0,
  "data": {
    "batch_id": "2bb2f0ec-a336-4a0a-b61a-241afaf9cc87"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### Batch Extraction Task Response Example

Source: https://mineru.net/apiManage/docs

Example JSON response structure returned by the batch extraction status endpoint.

```json

{
  "code": 0,
  "data": {
    "batch_id": "2bb2f0ec-a336-4a0a-b61a-241afaf9cc87",
    "extract_result": [
      {
        "file_name": "example.pdf",
        "state": "done",
        "err_msg": "",
        "full_zip_url": "https://cdn-mineru.openxlab.org.cn/pdf/018e53ad-d4f1-475d-b380-36bf24db9914.zip"
      },
      {
        "file_name": "demo.pdf",
        "state": "running",
        "err_msg": "",
        "extract_progress": {
          "extracted_pages": 1,
          "total_pages": 2,
          "start_time": "2025-01-20 11:43:20"
        }
      }
    ]
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}

```

--------------------------------

### Query Extract Result Response Examples

Source: https://mineru.net/apiManage/docs

JSON response payloads representing different task states.

```json

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b43605",
    "state": "waiting-file"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}

```

```json

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b43605",
    "state": "running"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}

```

```json

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b43605",
    "state": "done",
    "markdown_url": "https://cdn-mineru.openxlab.org.cn/pdf/a90e6ab6-.../full.md"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}

```

```json

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b43605",
    "state": "failed",
    "err_code": -30003,
    "err_msg": "file page count exceeds lightweight API limit (50 pages), please use the standard API"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}

```

--------------------------------

### Response Example for File Upload

Source: https://mineru.net/apiManage/docs

The JSON response structure containing the task ID and the signed OSS upload URL.

```json
{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b43605",
    "file_url": "https://oss-mineru.openxlab.org.cn/agent/a90e6ab6-...pdf?Expires=..."
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### Batch Extraction Response Example

Source: https://mineru.net/apiManage/docs

The JSON structure returned upon a successful batch extraction task creation.

```json
{
  "code": 0,
  "data": {
    "batch_id": "2bb2f0ec-a336-4a0a-b61a-241afaf9cc87",
    "file_urls": ["https://***"]
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### Batch URL Upload Extract in Python

Source: https://mineru.net/apiManage/docs

Use these examples to submit batch extraction tasks for documents or HTML files using the requests library.

```python

import requests

token = "token created on the API Management page"
url = "https://mineru.net/api/v4/extract/task/batch"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
data = {
    "files": [
        {"url":"https://cdn-mineru.openxlab.org.cn/demo/example.pdf", "data_id": "abcd"}
    ],
    "model_version": "vlm"
}
try:
    response = requests.post(url,headers=header,json=data)
    if response.status_code == 200:
        result = response.json()
        print('response success. result:{}'.format(result))
        if result["code"] == 0:
            batch_id = result["data"]["batch_id"]
            print('batch_id:{}'.format(batch_id))
        else:
            print('submit task failed,reason:{}'.format(result["msg"]))
    else:
        print('response not success. status:{} ,result:{}'.format(response.status_code, response))
except Exception as err:
    print(err)

```

```python

import requests

token = "token created on the API Management page"
url = "https://mineru.net/api/v4/extract/task/batch"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
data = {
    "files": [
        {"url":"https://***", "data_id": "abcd"}
    ],
    "model_version": "MinerU-HTML"
}
try:
    response = requests.post(url,headers=header,json=data)
    if response.status_code == 200:
        result = response.json()
        print('response success. result:{}'.format(result))
        if result["code"] == 0:
            batch_id = result["data"]["batch_id"]
            print('batch_id:{}'.format(batch_id))
        else:
            print('submit task failed,reason:{}'.format(result["msg"]))
    else:
        print('response not success. status:{} ,result:{}'.format(response.status_code, response))
except Exception as err:
    print(err)

```

--------------------------------

### cURL URL Extraction Request

Source: https://mineru.net/apiManage/docs

Example of using cURL to submit a file URL for extraction.

```bash
curl --location --request POST 'https://mineru.net/api/v1/agent/parse/url' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
    "language": "ch",
    "page_range": "1-10",
    "enable_table": true,
    "is_ocr": false,
    "enable_formula": true
}'
```

--------------------------------

### Query Task Status via API

Source: https://mineru.net/apiManage/docs

Use these examples to retrieve the current state and results of an extraction task. Ensure you have a valid API token and the task_id from the initial submission.

```python
import requests

token = "token created on the API Management page"
task_id = "task_id returned from the previous step"
url = f"https://mineru.net/api/v4/extract/task/{task_id}"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}

res = requests.get(url, headers=header)
print(res.status_code)
print(res.json())
print(res.json()["data"])
```

```bash
curl --location --request GET 'https://mineru.net/api/v4/extract/task/{task_id}' \
--header 'Authorization: Bearer *****' \
--header 'Accept: */*'
```

--------------------------------

### Query Batch Extraction Task Results

Source: https://mineru.net/apiManage/docs

Use these examples to retrieve the status of a batch extraction task. Ensure you have a valid API token and the correct batch_id.

```python

import requests

token = "token created on the API Management page"
batch_id = "batch_id returned from the previous step"
url = f"https://mineru.net/api/v4/extract-results/batch/{batch_id}"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}

res = requests.get(url, headers=header)
print(res.status_code)
print(res.json())
print(res.json()["data"])

```

```bash

curl --location --request GET 'https://mineru.net/api/v4/extract-results/batch/{batch_id}' \
--header 'Authorization: Bearer *****' \
--header 'Accept: */*'

```

--------------------------------

### Python URL Extraction Request

Source: https://mineru.net/apiManage/docs

Example of using the requests library to submit a PDF URL for extraction.

```python
import requests

url = "https://mineru.net/api/v1/agent/parse/url"

data = {
    "url": "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
    "language": "ch",
    "page_range": "1-10",
    "enable_table": True,
    "is_ocr": False,
    "enable_formula": True
}

res = requests.post(url, json=data)
print(res.json())
```

--------------------------------

### Query Extract Result Request

Source: https://mineru.net/apiManage/docs

Request the status of a task using the GET method.

```http
GET https://mineru.net/api/v1/agent/parse/{task_id}
```

```python

import requests

task_id = "a90e6ab6-44f3-4554-b459-b62fe4c6b43605"
url = f"https://mineru.net/api/v1/agent/parse/{task_id}"

res = requests.get(url)
print(res.json())

```

```bash

curl --location --request GET 'https://mineru.net/api/v1/agent/parse/{task_id}'

```

--------------------------------

### GET /parse/{task_id}

Source: https://mineru.net/apiManage/docs

Polls the status of a submitted extraction task.

```APIDOC
## GET /parse/{task_id}

### Description
Poll for the current state and result of an extraction task.

### Method
GET

### Endpoint
/parse/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The unique identifier for the extraction task.
```

--------------------------------

### GET /api/v4/extract-results/batch/{batch_id}

Source: https://mineru.net/apiManage/docs

Query the progress and results of a batch extraction task by providing the batch_id.

```APIDOC
## GET /api/v4/extract-results/batch/{batch_id}

### Description
Query batch extraction task progress and results by batch_id.

### Method
GET

### Endpoint
https://mineru.net/api/v4/extract-results/batch/{batch_id}

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The unique identifier for the batch task.

### Response
#### Success Response (200)
- **code** (int) - Status code, success: 0
- **msg** (string) - Processing message
- **trace_id** (string) - Request ID
- **data.batch_id** (string) - The batch_id
- **data.extract_result** (array) - List of extraction results

#### Response Example
{
  "code": 0,
  "data": {
    "batch_id": "2bb2f0ec-a336-4a0a-b61a-241afaf9cc87",
    "extract_result": [
      {
        "file_name": "example.pdf",
        "state": "done",
        "err_msg": "",
        "full_zip_url": "https://cdn-mineru.openxlab.org.cn/pdf/018e53ad-d4f1-475d-b380-36bf24db9914.zip"
      },
      {
        "file_name": "demo.pdf",
        "state": "running",
        "err_msg": "",
        "extract_progress": {
          "extracted_pages": 1,
          "total_pages": 2,
          "start_time": "2025-01-20 11:43:20"
        }
      }
    ]
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### GET https://mineru.net/api/v1/agent/parse/{task_id}

Source: https://mineru.net/apiManage/docs

Query the status and result of an extraction task by its unique task ID.

```APIDOC
## GET https://mineru.net/api/v1/agent/parse/{task_id}

### Description
Query the status and result of a extract task by `task_id`. Once the task is complete, the response includes a CDN download link for the Markdown result file.

### Method
GET

### Endpoint
https://mineru.net/api/v1/agent/parse/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The unique identifier for the extraction task.

### Response
#### Success Response (200)
- **code** (int) - Status code, success: 0
- **msg** (string) - Processing message, success: "ok"
- **trace_id** (string) - Request ID
- **data.task_id** (string) - Task ID
- **data.state** (string) - Task status: waiting-file, uploading, pending, running, done, failed
- **data.markdown_url** (string) - CDN download link for the Markdown result file, valid when state=done
- **data.err_msg** (string) - Error message, valid when state=failed
- **data.err_code** (int) - Error code, valid when state=failed

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b43605",
    "state": "done",
    "markdown_url": "https://cdn-mineru.openxlab.org.cn/pdf/a90e6ab6-.../full.md"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### GET /api/v4/extract/task/{task_id}

Source: https://mineru.net/apiManage/docs

Query the current progress of an extraction task by task_id. Once the task is complete, the endpoint responds with the extraction details.

```APIDOC
## GET /api/v4/extract/task/{task_id}

### Description
Query the current progress of an extraction task by task_id. Once the task is complete, the endpoint responds with the extraction details.

### Method
GET

### Endpoint
https://mineru.net/api/v4/extract/task/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The unique identifier returned from the extraction request.

### Response
#### Success Response (200)
- **code** (int) - Status code, success: 0
- **msg** (string) - Processing message, success: "ok"
- **trace_id** (string) - Request ID
- **data.task_id** (string) - Task ID
- **data.data_id** (string) - Data ID corresponding to the extract object
- **data.state** (string) - Task processing status: done, pending, running, failed, converting
- **data.full_zip_url** (string) - Extract result zip archive URL
- **data.err_msg** (string) - Failure reason, valid when state=failed
- **data.extract_progress.extracted_pages** (int) - Number of pages parsed, valid when state=running
- **data.extract_progress.start_time** (string) - Extract start time, valid when state=running
- **data.extract_progress.total_pages** (int) - Total number of pages, valid when state=running

### Response Example
{
  "code": 0,
  "data": {
    "task_id": "47726b6e-46ca-4bb9-******",
    "state": "done",
    "full_zip_url": "https://cdn-mineru.openxlab.org.cn/pdf/018e53ad-d4f1-475d-b380-36bf24db9914.zip",
    "err_msg": ""
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### CURL Signed Upload Flow

Source: https://mineru.net/apiManage/docs

A command-line implementation of the signed upload flow using curl.

```bash
# Step 1: Get signed upload URL
curl --location --request POST 'https://mineru.net/api/v1/agent/parse/file' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_name": "document.pdf",
    "language": "ch",
    "page_range": "1-10",
    "enable_table": true,
    "is_ocr": false,
    "enable_formula": true
}'

# Step 2: PUT upload file to the returned file_url
curl --location --request PUT '<file_url>' \
--data-binary '@document.pdf'
```

--------------------------------

### POST /parse/file

Source: https://mineru.net/apiManage/docs

Initiates a document extraction task by requesting a signed upload URL for a local file.

```APIDOC
## POST /parse/file

### Description
Submit a document extract task via file upload by obtaining a signed URL.

### Method
POST

### Endpoint
/parse/file

### Request Body
- **file_name** (string) - Required - Name of the file to upload.
- **language** (string) - Optional - Language code (default: "ch").
- **page_range** (string) - Optional - Range of pages to process.
- **enable_table** (boolean) - Optional - Enable table extraction (default: true).
- **is_ocr** (boolean) - Optional - Enable OCR (default: false).
- **enable_formula** (boolean) - Optional - Enable formula extraction (default: true).
```

--------------------------------

### Create Extract Task

Source: https://mineru.net/apiManage/docs

Submits a document URL for processing by the MinerU extraction service.

```APIDOC
## POST /create_extract_task

### Description
Creates a new document extraction task. The service processes the provided URL and returns a task ID for result polling or callback notification.

### Parameters
#### Request Body
- **url** (string) - Required - File URL, supports .pdf, .doc, .docx, .ppt, .pptx, Image(png/jpg/jpeg/jp2/webp/gif/bmp), .html formats
- **is_ocr** (bool) - Optional - Whether to enable OCR, default false.
- **enable_formula** (bool) - Optional - Whether to enable formula recognition, default true.
- **enable_table** (bool) - Optional - Whether to enable table recognition, default true.
- **language** (string) - Optional - Document language. Default `ch`.
- **data_id** (string) - Optional - Unique business data identifier.
- **callback** (string) - Optional - URL for callback notification of extract results.
- **seed** (string) - Optional - Random string used for signing callback notification requests.
- **extra_formats** ([string]) - Optional - Additional export formats (docx, html, latex).
- **page_ranges** (string) - Optional - Page range, e.g., "2,4-6".
- **model_version** (string) - Optional - MinerU model version (pipeline, vlm, MinerU-HTML).
- **no_cache** (bool) - Optional - Whether to bypass cache, default false.
- **cache_tolerance** (int) - Optional - Cache tolerance time in seconds, default 900.

### Response
#### Success Response (200)
- **code** (int) - Status code, success: 0
- **msg** (string) - Processing message
- **trace_id** (string) - Request ID
- **data.task_id** (string) - Extraction task ID

### Response Example
{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b4***"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### Python Signed Upload Flow

Source: https://mineru.net/apiManage/docs

A complete implementation of the signed upload flow using the requests library.

```python
import requests

# Step 1: Get signed upload URL
api_url = "https://mineru.net/api/v1/agent/parse/file"
data = {
    "file_name": "document.pdf",
    "language": "ch",
    "page_range": "1-10",
    "enable_table": True,
    "is_ocr": False,
    "enable_formula": True
}

res = requests.post(api_url, json=data)
result = res.json()
task_id = result["data"]["task_id"]
file_url = result["data"]["file_url"]

print(f"Task created, task_id: {task_id}")

# Step 2: PUT upload file to OSS
with open("document.pdf", "rb") as f:
    put_res = requests.put(file_url, data=f)
    print(f"File upload status: {put_res.status_code}")
```

--------------------------------

### Batch File Upload and Extraction in Python

Source: https://mineru.net/apiManage/docs

Python implementation for requesting upload URLs and performing file uploads for various document formats and HTML files.

```python

import requests

token = "token created on the API Management page"
url = "https://mineru.net/api/v4/file-urls/batch"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
data = {
    "files": [
        {"name":"demo.pdf", "data_id": "abcd"}
    ],
    "model_version":"vlm"
}
file_path = ["demo.pdf"]
try:
    response = requests.post(url,headers=header,json=data)
    if response.status_code == 200:
        result = response.json()
        print('response success. result:{}'.format(result))
        if result["code"] == 0:
            batch_id = result["data"]["batch_id"]
            urls = result["data"]["file_urls"]
            print('batch_id:{},urls:{}'.format(batch_id, urls))
            for i in range(0, len(urls)):
                with open(file_path[i], 'rb') as f:
                    res_upload = requests.put(urls[i], data=f)
                    if res_upload.status_code == 200:
                        print(f"{urls[i]} upload success")
                    else:
                        print(f"{urls[i]} upload failed")
        else:
            print('apply upload url failed,reason:{}'.format(result["msg"]))
    else:
        print('response not success. status:{} ,result:{}'.format(response.status_code, response))
except Exception as err:
    print(err)

```

```python

import requests

token = "token created on the API Management page"
url = "https://mineru.net/api/v4/file-urls/batch"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
data = {
    "files": [
        {"name":"demo.html", "data_id": "abcd"}
    ],
    "model_version":"MinerU-HTML"
}
file_path = ["demo.html"]
try:
    response = requests.post(url,headers=header,json=data)
    if response.status_code == 200:
        result = response.json()
        print('response success. result:{}'.format(result))
        if result["code"] == 0:
            batch_id = result["data"]["batch_id"]
            urls = result["data"]["file_urls"]
            print('batch_id:{},urls:{}'.format(batch_id, urls))
            for i in range(0, len(urls)):
                with open(file_path[i], 'rb') as f:
                    res_upload = requests.put(urls[i], data=f)
                    if res_upload.status_code == 200:
                        print(f"{urls[i]} upload success")
                    else:
                        print(f"{urls[i]} upload failed")
        else:
            print('apply upload url failed,reason:{}'.format(result["msg"]))
    else:
        print('response not success. status:{} ,result:{}'.format(response.status_code, response))
except Exception as err:
    print(err)

```

--------------------------------

### POST /api/v4/file-urls/batch

Source: https://mineru.net/apiManage/docs

Request a batch of upload URLs for files to be processed by the MinerU system.

```APIDOC
## POST /api/v4/file-urls/batch

### Description
Request upload URLs for a batch of files. After uploading the files to the returned URLs, the system automatically submits them for extraction.

### Method
POST

### Endpoint
https://mineru.net/api/v4/file-urls/batch

### Parameters
#### Request Body
- **files** (array) - Required - A list of file objects, each containing "name" (string) and "data_id" (string).
- **model_version** (string) - Required - The model version to use (e.g., "vlm" or "MinerU-HTML").

### Request Example
{
    "files": [
        {"name": "demo.pdf", "data_id": "abcd"}
    ],
    "model_version": "vlm"
}

### Response
#### Success Response (200)
- **code** (integer) - Status code (0 indicates success).
- **data** (object) - Contains "batch_id" (string) and "file_urls" (array of strings).

#### Response Example
{
    "code": 0,
    "data": {
        "batch_id": "...",
        "file_urls": ["https://..."],
        "msg": "success"
    }
}
```

--------------------------------

### POST /batch_url_upload

Source: https://mineru.net/apiManage/docs

Initiates a batch extraction task for files provided via URL.

```APIDOC
## POST /batch_url_upload

### Description
Initiates a batch extraction task for one or more files provided via URL. The service processes the files based on the specified model version and configuration parameters.

### Method
POST

### Request Body
- **enable_formula** (bool) - Optional - Whether to enable formula recognition, default true.
- **enable_table** (bool) - Optional - Whether to enable table recognition, default true.
- **language** (string) - Optional - Document language, default 'ch'.
- **file.url** (string) - Required - File URL, supports .pdf, .doc, .docx, .ppt, .pptx, Image, .html formats.
- **file.is_ocr** (bool) - Optional - Whether to enable OCR, default false.
- **file.data_id** (string) - Optional - Unique business data identifier.
- **file.page_ranges** (string) - Optional - Page range, e.g., '2,4-6'.
- **callback** (string) - Optional - URL for callback notification.
- **seed** (string) - Optional - Random string used for signing callback notifications.
- **extra_formats** ([string]) - Optional - Additional export formats (docx, html, latex).
- **model_version** (string) - Optional - MinerU model version (pipeline, vlm, MinerU-HTML).
- **no_cache** (bool) - Optional - Whether to bypass cache, default false.
- **cache_tolerance** (int) - Optional - Cache tolerance time in seconds, default 900.

### Request Example
{
  "files": [
    {
      "url": "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
      "data_id": "abcd"
    }
  ],
  "model_version": "vlm"
}

### Response
#### Success Response (200)
- **code** (int) - Status code, success: 0
- **msg** (string) - Processing message
- **trace_id** (string) - Request ID
- **data.batch_id** (string) - Batch extraction task ID

#### Response Example
{
  "code": 0,
  "data": {
    "batch_id": "2bb2f0ec-a336-4a0a-b61a-241afaf9cc87"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### Extract document via file upload

Source: https://mineru.net/apiManage/docs

Uploads a local file to OSS using a signed URL and polls for the extraction result. Requires the requests library and a local file path.

```python
import requests
import time

BASE_URL = "https://mineru.net/api/v1/agent"

def parse_by_file(file_path, language="ch", page_range=None, enable_table=True, is_ocr=False, enable_formula=True):
    """Submit a document extract task via file upload and wait for the result."""
    file_name = file_path.split("/")[-1].split("\\")[-1]

    # 1. Get signed upload URL
    data = {"file_name": file_name, "language": language, "enable_table": enable_table, "is_ocr": is_ocr, "enable_formula": enable_formula}
    if page_range:
        data["page_range"] = page_range

    resp = requests.post(f"{BASE_URL}/parse/file", json=data)
    result = resp.json()
    if result["code"] != 0:
        print(f"Failed to get upload URL: {result['msg']}")
        return None

    task_id = result["data"]["task_id"]
    file_url = result["data"]["file_url"]
    print(f"Task created, task_id: {task_id}")

    # 2. PUT upload file to OSS
    with open(file_path, "rb") as f:
        put_resp = requests.put(file_url, data=f)
        if put_resp.status_code not in (200, 201):
            print(f"File upload failed, HTTP {put_resp.status_code}")
            return None
    print("File uploaded successfully, waiting for extract...")

    # 3. Poll for result
    return poll_result(task_id)


def poll_result(task_id, timeout=300, interval=3):
    """Poll for extract result."""
    state_labels = {
        "pending": "Queued",
        "running": "Extracting",
        "waiting-file": "Waiting for file upload",
    }
    start = time.time()
    while time.time() - start < timeout:
        resp = requests.get(f"{BASE_URL}/parse/{task_id}")
        result = resp.json()
        state = result["data"]["state"]
        elapsed = int(time.time() - start)

        if state == "done":
            markdown_url = result["data"]["markdown_url"]
            print(f"[{elapsed}s] extract complete, Markdown download link: {markdown_url}")
            md_resp = requests.get(markdown_url)
            return md_resp.text

        if state == "failed":
            print(f"[{elapsed}s] extract failed: {result['data'].get('err_msg', 'Unknown error')}")
            return None

        print(f"[{elapsed}s] {state_labels.get(state, state)}...")
        time.sleep(interval)

    print(f"Polling timed out ({timeout}s), please manually query task_id: {task_id}")
    return None


# Usage example
content = parse_by_file("./document.pdf")
```

--------------------------------

### Create Single File Extract Task via cURL

Source: https://mineru.net/apiManage/docs

Execute extraction tasks using command-line tools. Ensure the Authorization header is correctly formatted with your token.

```bash
curl --location --request POST 'https://mineru.net/api/v4/extract/task' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "url": "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
    "model_version": "vlm"
}'
```

```bash
curl --location --request POST 'https://mineru.net/api/v4/extract/task' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "url": "https://****",
    "model_version": "MinerU-HTML"
}'
```

--------------------------------

### File Upload via cURL

Source: https://mineru.net/apiManage/docs

Perform the actual file upload using the URL obtained from the batch request.

```bash

curl -X PUT -T /path/to/your/file.pdf 'https://****'

```

--------------------------------

### Batch URL Upload Extract with cURL

Source: https://mineru.net/apiManage/docs

Use these cURL commands to trigger batch extraction tasks directly from the command line.

```bash

curl --location --request POST 'https://mineru.net/api/v4/extract/task/batch' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "files": [
        {"url":"https://cdn-mineru.openxlab.org.cn/demo/example.pdf", "data_id": "abcd"}
    ],
    "model_version": "vlm"
}'

```

```bash

curl --location --request POST 'https://mineru.net/api/v4/extract/task/batch' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "files": [
        {"url":"https://***", "data_id": "abcd"}
    ],
    "model_version": "MinerU-HTML"
}'

```

--------------------------------

### Create Single File Extract Task

Source: https://mineru.net/apiManage/docs

Submit a file URL for extraction. Requires a Bearer token in the Authorization header and supports different model versions based on file type.

```python
import requests

token = "token created on the API Management page"
url = "https://mineru.net/api/v4/extract/task"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
data = {
    "url": "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
    "model_version": "vlm"
}

res = requests.post(url,headers=header,json=data)
print(res.status_code)
print(res.json())
print(res.json()["data"])
```

```python
import requests

token = "token created on the API Management page"
url = "https://mineru.net/api/v4/extract/task"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
data = {
    "url": "https://****",
    "model_version": "MinerU-HTML"
}

res = requests.post(url,headers=header,json=data)
print(res.status_code)
print(res.json())
print(res.json()["data"])
```

--------------------------------

### POST https://mineru.net/api/v1/agent/parse/file

Source: https://mineru.net/apiManage/docs

Submit a file upload extract task to receive a task ID and a signed OSS upload URL.

```APIDOC
## POST https://mineru.net/api/v1/agent/parse/file

### Description
Submit a file upload extract task. The endpoint returns a task_id and an OSS signed upload URL (file_url) which the client uses to perform a PUT request to upload the file.

### Method
POST

### Endpoint
https://mineru.net/api/v1/agent/parse/file

### Parameters
#### Request Body
- **file_name** (string) - Required - File name (with extension), used to determine file type.
- **language** (string) - Optional - Extract language, affects OCR recognition. Default `ch`. Only effective for PDF files.
- **enable_table** (bool) - Optional - Whether to enable table recognition. Default `true`. Only effective for PDF files.
- **is_ocr** (bool) - Optional - Whether to enable OCR. Default `false`. Only effective for PDF files.
- **enable_formula** (bool) - Optional - Whether to enable formula recognition. Default `true`. Only effective for PDF files.
- **page_range** (string) - Optional - Page range, only effective for PDF. Supports `from-to` (e.g. `1-10`) or single page (e.g. `5`).

### Request Example
{
  "file_name": "document.pdf",
  "language": "ch",
  "page_range": "1-10",
  "enable_table": true,
  "is_ocr": false,
  "enable_formula": true
}

### Response
#### Success Response (200)
- **code** (int) - Status code, success: 0
- **msg** (string) - Processing message, success: "ok"
- **trace_id** (string) - Request ID
- **data.task_id** (string) - Extract task ID, used to query task results.
- **data.file_url** (string) - OSS signed upload URL; client PUTs the file to this address

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b43605",
    "file_url": "https://oss-mineru.openxlab.org.cn/agent/a90e6ab6-...pdf?Expires=..."
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### Request URL for File Upload

Source: https://mineru.net/apiManage/docs

The endpoint used to initiate the file upload process.

```text
POST https://mineru.net/api/v1/agent/parse/file
```

--------------------------------

### Batch File Upload Request via cURL

Source: https://mineru.net/apiManage/docs

cURL commands to request batch upload URLs for different file types.

```bash

curl --location --request POST 'https://mineru.net/api/v4/file-urls/batch' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "files": [
        {"name":"demo.pdf", "data_id": "abcd"}
    ],
    "model_version": "vlm"
}'

```

```bash

curl --location --request POST 'https://mineru.net/api/v4/file-urls/batch' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "files": [
        {"name":"demo.html", "data_id": "abcd"}
    ],
    "model_version": "MinerU-HTML"
}'

```

--------------------------------

### POST https://mineru.net/api/v1/agent/parse/url

Source: https://mineru.net/apiManage/docs

Submit a remote file URL for extraction. The backend downloads and parses the file asynchronously, returning a task_id for result polling.

```APIDOC
## POST https://mineru.net/api/v1/agent/parse/url

### Description
Submit a remote file URL for extract. The backend automatically downloads and parses the file. The endpoint operates asynchronously — upon successful submission, a `task_id` is returned.

### Method
POST

### Endpoint
https://mineru.net/api/v1/agent/parse/url

### Parameters
#### Request Body
- **url** (string) - Required - Remote file URL, supports PDF, images, Doc/Docx, PPT/PPTx, Xlsx formats.
- **file_name** (string) - Optional - File name (with extension), used to determine file type.
- **enable_table** (bool) - Optional - Whether to enable table recognition. Default `true`. Only effective for PDF files.
- **is_ocr** (bool) - Optional - Whether to enable OCR. Default `false`. Only effective for PDF files.
- **enable_formula** (bool) - Optional - Whether to enable formula recognition. Default `true`. Only effective for PDF files.
- **language** (string) - Optional - Extract language, affects OCR recognition. Default `ch`.
- **page_range** (string) - Optional - Page range, only effective for PDF. Supports `from-to` (e.g. `1-10`) or single page (e.g. `5`).

### Request Example
{
  "url": "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
  "language": "ch",
  "page_range": "1-10",
  "enable_table": true,
  "is_ocr": false,
  "enable_formula": true
}

### Response
#### Success Response (200)
- **code** (int) - Status code, success: 0
- **msg** (string) - Processing message, success: "ok"
- **trace_id** (string) - Request ID
- **data.task_id** (string) - Extract task ID, used to query task results.

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b43605"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}
```

--------------------------------

### Agent Lightweight Extract API

Source: https://mineru.net/apiManage/docs

The Agent Lightweight Extract API is designed for AI Agent workflows. It does not require a login but is subject to IP rate limits.

```APIDOC
## POST /api/v1/agent/parse/url
## POST /api/v1/agent/parse/file

### Description
Submit a single file or URL for lightweight extraction. Designed for AI Agent workflows with no authentication required.

### Method
POST

### Endpoint
/api/v1/agent/parse/url or /api/v1/agent/parse/file

### Parameters
- **IP Rate Limit** - Applied to prevent abuse.

### Notes
- File Size Limit: ≤ 10MB
- Page Limit: ≤ 20 pages
- Batch Support: Not supported (Single file only)
- Invocation: Async (submit → poll)
```
Tokens:
Raw