### Install MineruClient

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/getting-started/clients.mdx

Install the Python MineruClient wrapper from its GitHub repository.

```powershell
pip install "mineru-client @ git+https://github.com/sergeyshmakov/mineru-runpod@v1.1.0"
```

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

### Initialize MineruClient and Parse Document

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/README.md

Initialize the MineruClient with an endpoint ID and parse a document from a URL. This is a quick start example for Python integration.

```python
from mineru_client import MineruClient
client = MineruClient(endpoint_id="<your-endpoint-id>")
result = client.parse_document(file_url="https://example.com/report.pdf")
```

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

### Python Client Example for S3 Output

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/blog/2026-05-20-runpod-20mb-response-cap-r2-bridge.mdx

Example of using the MinerU client to parse a document and save the S3 output. The `return_format` is set to 's3', and the output is downloaded and extracted locally.

```python
result = client.parse_document(
    file_url="https://pub-....r2.dev/report.pdf",
    backend="vlm-auto-engine",
    return_format="s3",
)
# result["tarball_url"]            -> presigned R2 URL, valid ~1 h
# result["tarball_url_expires_in"] -> 3600
# result["bucket_key"]             -> "report-<hash>.tar.gz"

client.save_s3_tarball(result, "./out/")
# downloads + extracts -> out/report.md, out/report_content_list_v2.json, out/images/, ...
```

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

### Successful Job Logs

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/troubleshooting.mdx

Example JSON log entries for a successful job, including start and completion messages with timing details.

```json
{"ts":"2026-05-25T18:30:42.103Z","level":"info","logger":"mineru-worker","msg":"starting job","job_id":"queued-uuid-abc","backend":"vlm-auto-engine","lang":"en","start_page":0,"end_page":4,"gpu_name":"NVIDIA RTX 4090","compute_capability":"8.9"}
{"ts":"2026-05-25T18:30:48.612Z","level":"info","logger":"mineru-worker","msg":"done","job_id":"queued-uuid-abc","elapsed_seconds":6.51,"phase_ms":{"fetch_input":12,"mineru_parse":6420,"package":79},"model_dir":"/root/.cache/huggingface/hub/.../snapshots/<hash>","refresh_worker":false}
```

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

### Example Adapter for MinerU Output

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/getting-started/overview.mdx

Illustrates how to wrap the raw output from MinerU into a custom typed domain model. This is useful for integrating MinerU's structured data into your specific application logic.

```python
from typing import TypedDict, List
from mineru_client import MineruClient


class MyDocument(TypedDict):
    title: str
    sections: List[dict]


def parse_document_adapter(pdf_path: str) -> MyDocument:
    client = MineruClient()
    result = client.parse_document_from_file(pdf_path)

    # Example transformation: extract title and sections
    # This is a simplified example; real-world logic might be more complex.
    title = "Document Title Placeholder"
    sections = result.get("content_list", [])

    return MyDocument(title=title, sections=sections)


# Example usage:
doc_data = parse_document_adapter("/path/to/your/local/document.pdf")
print(doc_data)
```

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

### Scenario Analysis for Worker Boot Paths

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/troubleshooting.mdx

This table outlines different scenarios and their likely outcomes regarding worker boot paths, illustrating when to expect fast restores versus cold starts.

```text
Scenario | Likely outcome
--|--
`workers_min ≥ 1` | Worker stays on its host — every request is on a fully warm worker (~5 s parse, no cold start at all)
High-frequency endpoint, workers scale up and down fast | Same hosts get re-selected — most cold starts are happy-path restores (~7 s)
Quiet endpoint, infrequent requests, long idle gaps | RunPod's scheduler may pick a different host — some cold starts will be on new hosts (~110 s)
First request after a rebuild | Always cold path — every endpoint's first request after a fresh image pays ~5-7 min (image pull) + ~110 s (warmup). One-time cost per worker host.
`MINERU_SKIP_WARMUP=1` | Every cold start is ~110-130 s; no per-host amortization. Don't do this in production.
```

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

### Run Test Suite Locally

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/CONTRIBUTING.md

Install the test dependencies and run the test suite locally to ensure code changes meet the project's standards. CPU-only tests are preferred for CI.

```bash
pip install -e ".[test]" && pytest -v
```

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

### S3 Output Configuration Input

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/output-modes.mdx

Example input JSON to request output via S3 presigned URL. Requires S3-compatible bucket environment variables to be set.

```json
{
  "input": {
    "file_url": "https://example.com/large-book.pdf",
    "transport": "s3"
  }
}
```

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

### Configure MinerU Warmup Backend

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/troubleshooting.mdx

Specify the backend for MinerU warmup using MINERU_WARMUP_BACKEND. Ensure this matches the backend used by most callers to avoid cold starts on the first request.

```bash
MINERU_WARMUP_BACKEND=vlm-auto-engine
```

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

### PDF Input Example

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/input-formats.mdx

This snippet shows how to provide a PDF file via a URL for processing. The default backend `vlm-auto-engine` and `lang: "en"` are typically ignored for VLM input unless it's non-Latin.

```json
{
  "input": {
    "file_url": "https://example.com/report.pdf"
  }
}
```

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

### Pipeline Backend Configuration

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/choosing-gpu.mdx

Example JSON configuration for using the 'pipeline' backend with a specific language code. This is useful for non-Latin scripts or very long documents where memory predictability is key.

```json
{
  "input": {
    "file_url": "https://example.com/russian-report.pdf",
    "backend": "pipeline",
    "lang": "east_slavic"
  }
}
```

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

### Conventional Commits Example: Perf

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/CONTRIBUTING.md

Example of a commit message following the conventional commits format for a performance improvement, which triggers a patch version bump.

```bash
perf(handler): stream tarball instead of buffering
```

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

### Example Success Response (Truncated)

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/reference/api.mdx

This is a truncated example of a successful response when using the 'inline' transport with a Markdown format. The extracted Markdown content is found within the 'results' array.

```json
{
  "ok": true,
  "elapsed_seconds": 4.2,
  "mineru_version": "3.2.x",
  "results": [
    {
      "basename": "doc",
      "source": "url:https://example.com/report.pdf",
      "pages_requested": -1,
      "markdown": "# Document title\n\nFirst paragraph...\n\n## Section\n\nA table:\n\n<table>...</table>\n"
    }
  ],
  "debug": {"...": "..."}
}
```

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

### Parse PDF from URL using Python Client

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/getting-started/overview.mdx

Demonstrates how to use the MineruClient to parse a PDF document directly from a URL. Ensure the client is installed and the URL is accessible.

```python
from mineru_client import MineruClient

client = MineruClient()

# Example usage:
result = client.parse_document("https://example.com/path/to/your/document.pdf")

# result is a dict with keys like 'markdown', 'content_list', 'middle.json', 'images'
print(result)
```

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

### Conventional Commits Example: Feat

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/CONTRIBUTING.md

Example of a commit message following the conventional commits format for a feature addition, which triggers a minor version bump.

```bash
feat(client): add streaming response support
```

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

### Conventional Commits Example: Revert

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/CONTRIBUTING.md

Example of a commit message following the conventional commits format for reverting a previous change, which triggers a patch version bump.

```bash
revert: revert "feat: streaming response"
```

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

### Failure Response Example

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/reference/api.mdx

When a handler raises an error, the response includes an 'error' key and 'ok: false'. RunPod marks the job as FAILED.

```json
{
  "error": "ValueError: must provide exactly one of file_url / file_b64 / volume_path",
  "ok": false,
  "elapsed_seconds": 0.1,
  "mineru_version": "3.2.x",
  "traceback": "Traceback (most recent call last):\n  File ..."
}
```

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

### Example Job Input Contract

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/reference/api.mdx

This is a typical JSON payload sent to the worker for processing a document. It includes parameters for file source, page range, language, backend selection, and output formats.

```json
{
  "input": {
    "file_url":       "https://example.com/report.pdf",
    "start_page":     0,
    "end_page":       99,
    "lang":           "en",
    "backend":        "vlm-auto-engine",
    "formula_enable": true,
    "table_enable":   true,
    "transport":      "tarball_b64",
    "formats":        ["markdown", "content_list", "middle", "images"],
    "basename":       "my-doc"
  }
}
```

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

### S3 Output Response

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/output-modes.mdx

Example response when requesting output via S3. It includes a presigned tarball URL, its expiration time, and bucket key information.

```json
{
  "ok": true,
  "results": [
    {
      "basename": "doc",
      "source": "url:https://example.com/large-book.pdf",
      "pages_requested": -1,
      "tarball_url": "https://<bucket>.<endpoint>/<key>?<signature>",
      "tarball_url_expires_in": 3600,
      "bucket_key": "doc-<uuid>.tar.gz",
      "bucket_bytes": 87421344
    }
  ]
}
```

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

### Build Timeout Error

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/troubleshooting.mdx

RunPod's build pipeline has a 30-minute limit. Large model weights and dependency installations can exceed this. If timeouts persist, consider re-triggering the build, pinning a smaller VLM model for specific backends, or offloading models to RunPod's per-endpoint cache.

```text
Build exceeded maximum time limit of 1800 seconds (30.0 minutes). Build terminated.
```

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

### MinerU Worker Debug Block Example

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/troubleshooting.mdx

This JSON structure represents the debug information returned by a MinerU worker. It details the backend used, input format, model directory, GPU specifications, and processing times for different phases. Examine these fields to diagnose unexpected behavior.

```json
{
  "debug": {
    "backend": "vlm-auto-engine",
    "input_format": "pdf",
    "model_dir": "/root/.cache/huggingface/hub/models--opendatalab--MinerU2.5-Pro-2605-1.2B/snapshots/<hash>",
    "gpu": {
      "available": true,
      "name": "NVIDIA RTX 4090",
      "compute_capability": "8.9",
      "total_memory_gb": 23.99
    },
    "phase_ms": {
      "fetch_input": 12,
      "mineru_parse": 18420,
      "package": 95
    }
  }
}
```

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

### Conventional Commits Example: Refactor

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/CONTRIBUTING.md

Example of a commit message following the conventional commits format for a code refactor, which triggers a patch version bump.

```bash
refactor(client): split parse_document into smaller helpers
```

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

### Conventional Commits Example: Fix

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/CONTRIBUTING.md

Example of a commit message following the conventional commits format for a bug fix, which triggers a patch version bump.

```bash
fix(handler): handle PDFs with empty page_range
```

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

### Deploy Serverless Endpoint from Forked Repository

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/getting-started/deploy.mdx

Use this command-line script to deploy a serverless endpoint from your forked GitHub repository. Ensure you have filled in your RunPod API key and the MinerU template ID in the .env file.

```powershell
cp .env.example .env       # fill RUNPOD_API_KEY and MINERU_TEMPLATE_ID
pip install -e .[deploy]
python deploy.py --template-id $env:MINERU_TEMPLATE_ID
```

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

### Deploy MinerU with specific GPU IDs from deploy.py

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/choosing-gpu.mdx

This command deploys MinerU using a specified template ID and a list of preferred GPU IDs. RunPod will select the first available pool from the list during scale-up.

```powershell
python deploy.py --template-id $env:MINERU_TEMPLATE_ID --gpu-ids AMPERE_48
```

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

### Fresh Boot Worker Logs (Request 3)

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/blog/2026-05-26-runpod-flashboot-mechanism-investigation.mdx

Logs from a worker experiencing a full fresh boot, including image pull, fitness checks, and vLLM engine initialization. This demonstrates the complete startup sequence before a request is processed.

```log
04:45:45  Running 7 fitness check(s)...
04:45:46  All fitness checks passed. (1285.99ms)
04:45:46  [mineru-warmup] starting (backend=vlm-auto-engine ...)
04:45:51  Using vllm-async-engine as the inference engine for VLM.
04:46:23  Initializing a V1 LLM engine (v0.11.2) ...
04:46:47  Model loading took 2.1601 GiB memory and 18.41 seconds
04:47:14  torch.compile takes 22.81 s in total
04:47:17  init engine (profile, create kv cache, warmup model) took 30.66 seconds
04:47:18  get vllm-async-engine predictor cost: 87.26s
04:47:28  [mineru-warmup] done in 101.5s
04:47:28  Jobs in queue: 1
04:47:28  Started.
04:47:28  "starting job" {...}
04:47:34  "done" {...elapsed_seconds: 5.58...}
```

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

### Conventional Commits Example: Breaking Change

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/CONTRIBUTING.md

Example of a commit message indicating a breaking change, which forces a major version bump regardless of the type. Includes a BREAKING CHANGE footer.

```bash
feat(client)!: rename parse_document to parse

BREAKING CHANGE: parse_document is now parse. Callers must update imports.
```

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

### Failed Job Log

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/troubleshooting.mdx

Example JSON log entry for a job that failed, indicating the error type and message.

```json
{"ts":"2026-05-25T18:30:42.789Z","level":"error","logger":"mineru-worker","msg":"job failed","job_id":"queued-uuid-abc","error_type":"ValueError","error_message":"input bytes do not match any supported format","phase_ms":{"fetch_input":8}}
```

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

### S3 Transport Error Message

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/output-modes.mdx

Example error message when S3 transport is requested but required environment variables are not set.

```text
ValueError: transport='s3' requires worker env vars: BUCKET_ENDPOINT_URL, BUCKET_NAME, BUCKET_ACCESS_KEY_ID, BUCKET_SECRET_ACCESS_KEY. Set these in the RunPod endpoint env config and redeploy.
```

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

### Deploy MinerU with a fallback GPU ID list

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/choosing-gpu.mdx

This command deploys MinerU with a preferred list of GPU IDs, including fallbacks. RunPod attempts to use the GPUs in the order provided.

```powershell
python deploy.py --template-id ... --gpu-ids "ADA_24,AMPERE_24,AMPERE_48"
```

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

### Deploy Serverless Endpoint with Custom Docker Image

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/getting-started/deploy.mdx

Deploy a serverless endpoint using a pre-built Docker image. This method bypasses RunPod's auto-build process, offering full control over the Docker layer.

```python
python deploy.py --image yourhandle/mineru-runpod:0.1
```

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

### Parse Document with RunPod SDK (Python)

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/README.md

This snippet demonstrates using the RunPod SDK in Python for asynchronous or synchronous execution. It shows how to set the API key, initialize an endpoint object, and run a sync job with the input payload.

```APIDOC
## Parse Document with RunPod SDK (Python)

### Description
Integrates with the RunPod SDK in Python for executing parsing jobs. This method supports synchronous (`run_sync`) and potentially asynchronous operations, suitable for production workflows.

### Method
`endpoint.run_sync(input_payload)`

### Parameters
#### Client Initialization
```python
import runpod
runpod.api_key = "<your-runpod-api-key>"
endpoint = runpod.Endpoint("<your-endpoint-id>")
```

#### Input Payload
- **input** (object) - Required - Contains the parameters for the parsing job.
  - **file_url** (string) - Required - The URL of the document to parse.
  - **end_page** (integer) - Optional - The last page to parse.
  - **transport** (string) - Optional - Specifies how the output is delivered. Options: `tarball_b64` (default), `inline`, `s3`. Requires `BUCKET_*` env vars if `s3` is used.
  - **formats** (array of strings) - Optional - Filters the output formats. Options: `markdown`, `content_list`, `middle`, `images`. Defaults to all four.

### Request Example
```python
import runpod

runpod.api_key = "..."
endpoint = runpod.Endpoint("<endpoint-id>")

input_data = {
    "input": {
        "file_url": "https://example.com/report.pdf",
        "end_page": 4,
        "transport": "inline"
    }
}

result = endpoint.run_sync(input_data)
```

### Response
#### Success Response
The `result` variable will contain the output from the RunPod job, structured similarly to the HTTP API response. For synchronous calls, it directly returns the result. For asynchronous calls, it would return a job ID.

#### Response Example (for `run_sync`)
```json
{
  "output": {
    "results": [
      {
        "markdown": "# Parsed Document\n..."
      }
    ]
  }
}
```
```

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

### Fork and Clone MinerU Repository

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/blog/2026-05-19-launching-mineru-runpod.mdx

Clone the mineru-runpod repository to your local machine to begin the deployment process. This sets up the necessary files for RunPod integration.

```sh
gh repo fork sergeyshmakov/mineru-runpod --clone
cd mineru-runpod
```

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

### FlashBoot Lookup Model

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/troubleshooting.mdx

This model describes the FlashBoot lookup process and its impact on worker boot times. It highlights the difference between restoring a snapshot and performing a fresh boot.

```text
FlashBoot lookup = (worker host, image SHA)
- match → restore snapshot in ~3 s, parse in ~5 s → ~7-8 s wall-clock
- no match → fresh boot, run fitness checks + warmup → ~110 s wall-clock
```

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

### Configure HTTP-client backend with external vLLM server

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/choosing-gpu.mdx

Use this JSON configuration when employing `vlm-http-client` or `hybrid-http-client` to specify the external vLLM server URL. This allows workers to remain small and stateless.

```json
{
  "input": {
    "file_url": "...",
    "backend": "vlm-http-client",
    "server_url": "https://your-vllm-host.example.com/v1"
  }
}
```

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

### tarball_b64 Response Example

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/output-modes.mdx

A typical response for 'tarball_b64' transport includes a base64-encoded .tar.gz of the output. This mode is limited by the RunPod gateway's ~20 MB response cap.

```json
{
  "ok": true,
  "results": [
    {
      "basename": "doc",
      "source": "url:https://example.com/report.pdf",
      "pages_requested": -1,
      "tarball_b64": "<base64-encoded .tar.gz, ~1-15 MB typically>"
    }
  ]
}
```

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

### Deploy MinerU Endpoint via Python Script

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/blog/2026-05-19-launching-mineru-runpod.mdx

Use the provided Python script to deploy the MinerU endpoint to RunPod Serverless. This script allows for reproducible deployments by exposing endpoint settings as CLI flags.

```python
pip install -e .[deploy]
python deploy.py --template-id <tid>
```

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

### inline Response Example

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/output-modes.mdx

The 'inline' transport response provides parsed artifacts like markdown, content_list, middle JSON, and images as base64-encoded strings. This is useful for services that render markdown directly.

```json
{
  "ok": true,
  "results": [
    {
      "basename": "doc",
      "source": "url:https://example.com/report.pdf",
      "pages_requested": -1,
      "markdown": "# Heading\n\nBody text...",
      "content_list": [{"type": "text", "page_idx": 0, "text": "..."}],
      "middle": {"...": "..."},
      "images": {"img-1.png": "<base64>", "img-2.png": "<base64>"}
    }
  ]
}
```

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

### Configure default GPU pool list in hub.json

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/choosing-gpu.mdx

This JSON configuration within `.runpod/hub.json` sets the default list of GPU IDs for a published Hub template. Users will see this list when deploying the template.

```json
{
  "config": {
    "gpuIds": "ADA_24,AMPERE_24,AMPERE_48",
    ...
  }
}
```

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

### Mineru Job Response (Inline Transport)

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/getting-started/clients.mdx

Example of a successful Mineru job response with the 'inline' transport. This format provides parsed content directly, including markdown, text content, and images.

```json
{
  "ok": true,
  "elapsed_seconds": 18.4,
  "mineru_version": "3.2.x",
  "results": [
    {
      "basename": "doc",
      "source": "url:https://...",
      "pages_requested": 100,
      "markdown": "# Heading\n\nBody text...",
      "content_list": [{"type": "text", "page_idx": 0, "text": "..."}],
      "middle": {"...": "..."},
      "images": {"img-1.png": "<base64>"}
    }
  ],
  "debug": {"...": "..."}
}
```

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

### Parse PDF from File using Python Client

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/getting-started/overview.mdx

Shows how to parse a local PDF file using the MineruClient. The file path should be valid and accessible by the client.

```python
from mineru_client import MineruClient

client = MineruClient()

# Example usage:
result = client.parse_document_from_file("/path/to/your/local/document.pdf")

# result is a dict with keys like 'markdown', 'content_list', 'middle.json', 'images'
print(result)
```

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

### Snapshot Restore Worker Logs (Request 4)

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/blog/2026-05-26-runpod-flashboot-mechanism-investigation.mdx

Logs from a worker that has been restored from a FlashBoot snapshot. This shows a significantly shorter startup time as it bypasses the full boot sequence.

```log
04:51:25  Jobs in queue: 1
04:51:25  Started.
04:51:25  "starting job" {...}
04:51:26  Using vllm-async-engine ...   (instant — engine handle restored from snapshot)
04:51:30  "done" {...elapsed_seconds: 4.58...}
```

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

### Mineru Job Response (Tarball Base64)

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/getting-started/clients.mdx

Example of a successful Mineru job response when using the default 'tarball_b64' transport. This format includes job metadata and parsed file content encoded in base64.

```json
{
  "ok": true,
  "elapsed_seconds": 18.4,
  "mineru_version": "3.2.x",
  "results": [
    {
      "basename": "doc",
      "source": "url:https://...",
      "pages_requested": 100,
      "tarball_b64": "..."
    }
  ],
  "debug": {"...": "..."}
}
```

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

### POST /v2/{endpoint_id}/runsync or POST /run

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/reference/api.mdx

Send a POST request to the /v2/{endpoint_id}/runsync or /run endpoint with a JSON payload containing the job input configuration.

```APIDOC
## POST /v2/{endpoint_id}/runsync or POST /run

### Description
Send a POST request to the `/v2/{endpoint_id}/runsync` (for synchronous jobs) or `/run` (for asynchronous jobs) endpoint with a JSON payload. The payload must contain an `input` object that specifies the job configuration.

### Method
POST

### Endpoint
`/v2/{endpoint_id}/runsync` or `/run`

### Parameters

#### Request Body

- **input** (object) - Required - The main configuration object for the job.
  - **file_url** (string) - Required (exactly one of `file_url`, `file_b64`, `volume_path`) - Public or presigned HTTP/HTTPS URL for the input file.
  - **file_b64** (string) - Required (exactly one of `file_url`, `file_b64`, `volume_path`) - Base64-encoded file bytes. Subject to payload size limits.
  - **volume_path** (string) - Required (exactly one of `file_url`, `file_b64`, `volume_path`) - Absolute path to a file inside the container, useful for mounted volumes.
  - **start_page** (int) - Optional - 0-based inclusive start page. Defaults to `0`.
  - **end_page** (int) - Optional - 0-based inclusive end page. Defaults to `-1` (end of document).
  - **lang** (string) - Optional - Language hint for pipeline backends. Defaults to `"en"`.
  - **backend** (string) - Optional - The processing backend to use. Defaults to `"vlm-auto-engine"`.
  - **server_url** (string) - Optional - Required for `*-http-client` backends. URL of an external vLLM OpenAI-compatible server.
  - **formula_enable** (bool) - Optional - Whether to extract LaTeX equations. Defaults to `true`.
  - **table_enable** (bool) - Optional - Whether to extract structured HTML tables. Defaults to `true`.
  - **transport** (string) - Optional - How the worker ships output. Defaults to `"tarball_b64"`.
  - **formats** (array of string) - Optional - Subset of `["markdown", "content_list", "middle", "images"]` to select artifacts for inline transport. No-op for `tarball_b64` and `s3`.
  - **basename** (string) - Optional - Filename stem for output files. Defaults to `"doc"`.

### Request Example
```json
{
  "input": {
    "file_url": "https://example.com/report.pdf",
    "start_page": 0,
    "end_page": 99,
    "lang": "en",
    "backend": "vlm-auto-engine",
    "formula_enable": true,
    "table_enable": true,
    "transport": "tarball_b64",
    "formats": ["markdown", "content_list", "middle", "images"],
    "basename": "my-doc"
  }
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the job was successful.
- **elapsed_seconds** (number) - The time taken for the job in seconds.
- **mineru_version** (string) - The version of the mineru worker.
- **results** (array) - An array containing the results of the job. Each result object may contain fields like `basename`, `source`, `pages_requested`, and `markdown`.
- **debug** (object) - Contains debug information.

#### Response Example
```json
{
  "ok": true,
  "elapsed_seconds": 4.2,
  "mineru_version": "3.2.x",
  "results": [
    {
      "basename": "doc",
      "source": "url:https://example.com/report.pdf",
      "pages_requested": -1,
      "markdown": "# Document title\n\nFirst paragraph...\n\n## Section\n\nA table:\n\n<table>...</table>\n"
    }
  ],
  "debug": {"...": "..."}
}
```
```

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

### Example CUDA Error on Blackwell GPU

Source: https://github.com/sergeyshmakov/mineru-runpod/blob/main/docs/src/content/docs/guides/choosing-gpu.mdx

This error occurs when using the VLM backend on a Blackwell GPU (compute capability 12.0) due to incompatible kernels in the worker image's xformers/flash-attn. The pipeline backend may still function.

```text
CUDA error (...flash-attention/hopper/flash_fwd_launch_template.h:188): invalid argument
```