Referencia

Clientes

import markpdf

client = markpdf.Client(
    api_key="YOUR_API_KEY",     # or MARKPDF_API_KEY environment variable
    base_url="https://api.markpdf.tech",  # optional, production default
    timeout=300,               # segundos, default 300
    max_retries=2,             # reintentos automáticos en 429/5xx
)

import markpdf

client = markpdf.AsyncClient(
    api_key="YOUR_API_KEY",
    base_url="https://api.markpdf.tech",
    timeout=300,
    max_retries=2,
)

string

required

Your API key. If you don’t pass it, the client reads MARKPDF_API_KEY from the environment.

string

default:"https://api.markpdf.tech"

URL base of API. Change it only if you use your own proxy.

float

default:"300"

Timeout in seconds per request HTTP. Large documents in mode=quality may take longer; upload it if you need it.

integer

default:"2"

Automatic retries with exponential backoff in 429 and 5xx. See Error Handling.

AsyncClient implements the async context manager protocol (async with) to successfully close the HTTP session. Client also supports with.

Methods common to both clients

All methods accept the same named parameters as the conversion API. AsyncClient exposes the same signature with await.

`convert_file`

client.convert_file(
    path: str | Path,
    *,
    input_format: str = "auto",
    mode: str = "fast",
    engine: str = "auto",
    clean: bool = True,
    response_format: str = "markdown",
    pages: str | None = None,
    output_url: str | None = None,
    output_encoding: str = "identity",
    output_head_url: str | None = None,
    auto_poll: bool = True,
) -> str | ConversionResult

Upload a local file to POST /convert/raw with the contents compressed to gzip if it exceeds 1MB (transparent, no configuration required). Returns str with Markdown, or ConversionResult if response_format="json".

str | Path

required

Path to local file.

boolean

default:"true"

If the server responds 202 (backends saturated), SDK automatically polls from GET /jobs/{id} to completed or failed. With auto_poll=Failedse, the method casts MarkpdfJobQueuedError with the job_id so you can do the poll yourself. See Streaming and async.

`convert_from_url`

client.convert_from_url(
    url: str,
    *,
    filename: str | None = None,
    input_format: str = "auto",
    mode: str = "fast",
    engine: str = "auto",
    clean: bool = True,
    response_format: str = "markdown",
    pages: str | None = None,
    output_url: str | None = None,
    output_encoding: str = "identity",
    output_head_url: str | None = None,
    auto_poll: bool = True,
) -> str | ConversionResult

Call POST /convert/from-url. url must be a pre-signed URL accessible by HTTPS.

`convert_stream`

client.convert_stream(
    path: str | Path | None = None,
    *,
    url: str | None = None,
    filename: str | None = None,
    input_format: str = "auto",
    clean: bool = True,
    slim: bool = True,
    stream_slim_strategy: str = "sampled",
) -> Iterator[str]  # AsyncIterator[str] en AsyncClient

Returns an iterator that produces Markdown fragments as they arrive via streaming (POST /convert/stream or /convert/stream-from-url depending on path or url passes). See Streaming and async.

`pdf_index`

client.pdf_index(url: str, *, filename: str | None = None) -> PdfSpine

Call POST /pdf/index. Returns a PdfSpine object typed with page_count, sections, pages, font_model, estimated_tokens_full, etc. — same fields documented by POST /pdf/index.

spine = client.pdf_index("https://bucket.example.com/report.pdf?sig=...")
for section in spine.sections:
    print(section.page, section.level, section.text)

`get_job`

client.get_job(job_id: str) -> JobStatus

Manually query GET /jobs/{id}. JobStatus.status is one of "queued", "processing", "completed", "failed". When status == "completed", JobStatus.body contains the original result (Markdown or JSON depending on the parameters of the queued conversion).

Return Types

`ConversionResult`

str

Converted document.

str

Name of the processed document.

str

Formato detectado o forzado.

str

Engine that produced the output.

int

Input document size.

int

Output Markdown size.

int

Estimated saved tokens vs. raw document.

Timings

convert_ms, clean_ms, total_worker_ms, upload_ms, total_request_ms.

`PdfSpine`

int

list[Section]

Each Section has page, level, text.

list[PageInfo]

Each PageInfo has page, chars, first_line, headings.

bool

int

`JobStatus`

str

"queued", "processing", "completed" o "failed".

str | dict | None

Present only when status == "completed".

str | None

Present only when status == "failed".

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Referencia

Referencia

Clientes

Methods common to both clients

`convert_file`

`convert_from_url`

`convert_stream`

`pdf_index`

`get_job`

Return Types

`ConversionResult`

`PdfSpine`

`JobStatus`

​Referencia

​Clientes

​Methods common to both clients

​convert_file

​convert_from_url

​convert_stream

​pdf_index

​get_job

​Return Types

​ConversionResult

​PdfSpine

​JobStatus

Referencia

Clientes

Methods common to both clients

`convert_file`

`convert_from_url`

`convert_stream`

`pdf_index`

`get_job`

Return Types

`ConversionResult`

`PdfSpine`

`JobStatus`