FastAPI Service (mineru-api)

Relevant source files

• mineru/backend/hybrid/hybrid_analyze.py
• mineru/backend/hybrid/hybrid_model_output_to_middle_json.py
• mineru/cli/client.py
• mineru/cli/common.py
• mineru/cli/fast_api.py
• mineru/cli/gradio_app.py
• mineru/resources/header.html
• mineru/utils/cli_parser.py
• mineru/utils/pdf_text_tool.py
• mineru/utils/span_pre_proc.py

The FastAPI service (mineru-api) is a REST API server that provides HTTP endpoints for PDF document parsing. It exposes MinerU's parsing capabilities through an OpenAPI-compliant web service, enabling integration with external applications and distributed processing architectures.

For command-line usage, see Command Line Interface (mineru). For the Gradio web interface, see Gradio Web UI (mineru-gradio). For the OpenAI-compatible server, see OpenAI-Compatible Server.

---

Architecture Overview

The FastAPI service acts as an HTTP wrapper around MinerU's core processing pipeline, providing asynchronous request handling and flexible output formats.

Sources: mineru/cli/fast_api.py1-452 mineru/cli/common.py32-43 mineru/cli/common.py486-556

---

Service Initialization

The FastAPI application is created through the create_app() function, which configures middleware, concurrency controls, and documentation endpoints.

Configuration Options

Configuration	Type	Default	Description
MINERU_API_ENABLE_FASTAPI_DOCS	Environment Variable	1	Enable/disable OpenAPI docs at /docs and /redoc
MINERU_API_MAX_CONCURRENT_REQUESTS	Environment Variable	0 (unlimited)	Maximum concurrent requests allowed
--host	CLI Argument	127.0.0.1	Server bind address
--port	CLI Argument	8000	Server port
--reload	CLI Flag	False	Enable auto-reload for development

Sources: mineru/cli/fast_api.py49-80 mineru/cli/fast_api.py423-447

---

API Endpoint: /file_parse

The primary endpoint accepts multipart file uploads and returns parsed document content in JSON or ZIP format.

Request Parameters

Sources: mineru/cli/fast_api.py126-199

Backend Options

The backend parameter determines the parsing engine:

Backend	Description	Requirements
pipeline	Traditional multi-model pipeline	CPU-friendly, hallucination-free
vlm-auto-engine	High-accuracy VLM processing	Local GPU, Chinese/English only
vlm-http-client	Remote VLM processing	Requires server_url
hybrid-auto-engine	VLM + specialized models	Local GPU, multi-language
hybrid-http-client	Remote VLM + local models	Requires server_url + local GPU

Sources: mineru/cli/fast_api.py154-162

---

Request Processing Flow

Sources: mineru/cli/fast_api.py125-421 mineru/cli/fast_api.py35-46 mineru/cli/common.py32-43 mineru/cli/common.py486-556 mineru/cli/common.py94-169

---

Response Formats

JSON Response Structure

When response_format_zip=False, the service returns a JSON object:

The results dictionary contains one entry per uploaded file, keyed by the file's stem name. Each entry includes:

• md_content: Markdown output (if return_md=True)
• middle_json: Intermediate processing format (if return_middle_json=True)
• model_output: Raw model inference results (if return_model_output=True)
• content_list: Structured content list (if return_content_list=True)
• images: Base64-encoded extracted images (if return_images=True)

Sources: mineru/cli/fast_api.py360-415

ZIP Response Structure

When response_format_zip=True, the service returns a ZIP archive with this structure:

results.zip
├── document_name/
│   ├── document_name.md
│   ├── document_name_middle.json
│   ├── document_name_model.json
│   ├── document_name_content_list.json
│   └── images/
│       ├── image_0.jpg
│       └── image_1.jpg

File names are sanitized using sanitize_filename() to prevent directory traversal attacks.

Sources: mineru/cli/fast_api.py273-359 mineru/cli/fast_api.py83-94

---

Concurrency Control

The service implements optional request throttling to prevent resource exhaustion:

The concurrency limit is configured via:

If MINERU_API_MAX_CONCURRENT_REQUESTS=0 or unset, no limit is enforced.

Sources: mineru/cli/fast_api.py30-47 mineru/cli/fast_api.py63-74 mineru/cli/fast_api.py436-441

---

File Handling and Security

Input Validation

The service validates uploaded files through multiple checks:

1. File Type Detection: Uses guess_suffix_by_path() to verify file extensions (mineru/utils/guess_suffix_or_lang.py)
2. Format Support: Only accepts files in pdf_suffixes + image_suffixes lists defined in mineru/cli/common.py27-28
3. Conversion: Applies read_fn() to normalize inputs to PDF bytes:
   • Images are converted to PDF via images_bytes_to_pdf_bytes() (mineru/cli/common.py39)
   • PDFs are returned as-is (mineru/cli/common.py40-41)
   • Unknown formats raise an exception (mineru/cli/common.py43)

The validation flow:

Sources: mineru/cli/fast_api.py213-239 mineru/cli/common.py27-43

Filename Sanitization

The sanitize_filename() function prevents directory traversal attacks:

Sources: mineru/cli/fast_api.py83-94

Temporary File Cleanup

All temporary files and directories are cleaned up via background tasks:

The cleanup_file() function handles both files and directories recursively.

Sources: mineru/cli/fast_api.py96-106 mineru/cli/fast_api.py207 mineru/cli/fast_api.py276

---

Integration with Core Processing

The FastAPI service delegates all parsing logic to aio_do_parse() from mineru/cli/common.py:

The service sets output flags based on the request parameters:

Request Parameter	Common.py Flag	Default in API
return_md	f_dump_md	True
return_middle_json	f_dump_middle_json	False
return_model_output	f_dump_model_output	False
return_content_list	f_dump_content_list	False
N/A	f_draw_layout_bbox	False (hardcoded)
N/A	f_draw_span_bbox	False (hardcoded)
N/A	f_dump_orig_pdf	False (hardcoded)

Debug outputs (layout/span PDFs) are disabled in the API to reduce response size.

Sources: mineru/cli/fast_api.py250-270 mineru/cli/common.py486-556 mineru/cli/common.py85-91 mineru/cli/common.py171-224 mineru/cli/common.py226-265 mineru/cli/common.py361-412

---

Starting the Service

Command-Line Invocation

Accessing Documentation

When MINERU_API_ENABLE_FASTAPI_DOCS is enabled (default):

• Swagger UI: http://<host>:<port>/docs
• ReDoc: http://<host>:<port>/redoc
• OpenAPI Schema: http://<host>:<port>/openapi.json

To disable documentation in production:

Sources: mineru/cli/fast_api.py443-447 mineru/cli/fast_api.py51-61

---

Configuration Passing Mechanism

The main() function uses a two-level configuration system:

1. CLI Arguments: Parsed by Click decorators (--host, --port, --reload)
2. Extra Arguments: Parsed by arg_parse(ctx) for backend-specific parameters

Extra arguments are stored in app.state.config and passed to aio_do_parse():

This allows passing VLM inference engine parameters directly:

Sources: mineru/cli/fast_api.py423-447 mineru/cli/fast_api.py200-201 mineru/cli/fast_api.py269

---

Output Directory Structure

The service creates a unique temporary directory for each request:

output_dir/
└── <uuid>/
    ├── document_name/
    │   └── <backend_specific_dir>/
    │       ├── document_name.md
    │       ├── document_name_middle.json
    │       ├── document_name_model.json
    │       ├── document_name_content_list.json
    │       ├── document_name_content_list_v2.json  (VLM/Hybrid only)
    │       └── images/
    │           └── *.jpg

The <backend_specific_dir> naming is determined by the backend detection logic:

Backend Parameter	Directory Name	Code Reference
pipeline	{parse_method} (auto/txt/ocr)	mineru/cli/fast_api.py283
vlm-*	vlm	mineru/cli/fast_api.py285
hybrid-*	hybrid_{parse_method}	mineru/cli/fast_api.py287-289

The directory structure is created by prepare_env() in mineru/cli/common.py46-51:

Sources: mineru/cli/fast_api.py205-207 mineru/cli/fast_api.py282-293 mineru/cli/fast_api.py367-378 mineru/cli/common.py46-51

---

Error Handling

The service returns appropriate HTTP status codes:

Status Code	Condition	Response
200	Success	JSON or ZIP response with parsed content
400	Invalid file type	{"error": "Unsupported file type: ..."}
400	File load failure	{"error": "Failed to load file: ..."}
500	Processing exception	{"error": "Failed to process file: ..."}
503	At capacity	{"detail": "Server is at maximum capacity: ..."}

All exceptions are logged with full tracebacks via logger.exception().

Sources: mineru/cli/fast_api.py231-239 mineru/cli/fast_api.py416-420 mineru/cli/fast_api.py38-42

---

Middleware Configuration

The FastAPI app includes GZip compression middleware:

This automatically compresses responses larger than 1KB, significantly reducing bandwidth for large JSON responses or markdown files.

Sources: mineru/cli/fast_api.py76

---

Language List Handling

The service ensures the lang_list parameter matches the number of uploaded files:

This prevents indexing errors when a single language is specified for multiple documents.

Sources: mineru/cli/fast_api.py242-247