> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia

> Clases, métodos y opciones de cliente Python.

\#Referencia

## Clientes

<CodeGroup>
  ```python Client (síncrono) theme={null}
  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
  )
  ```

  ```python AsyncClient (asíncrono) theme={null}
  import markpdf

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

<ParamField body="api_key" type="string" required>
  Su clave API. Si no lo pasa, el cliente lee `MARKPDF_API_KEY` del entorno.
</ParamField>

<ParamField body="base_url" type="string" default="https://api.markpdf.tech">
  URL base de API. Cámbielo solo si usa su propio proxy.
</ParamField>

<ParamField body="timeout" type="float" default="300">
  Tiempo de espera en segundos por solicitud HTTP. Los documentos grandes en `mode=quality` pueden tardar más; súbelo si lo necesitas.
</ParamField>

<ParamField body="max_retries" type="integer" default="2">
  Reintentos automáticos con retroceso exponencial en `429` y `5xx`. Consulte [Manejo de errores](/docs/public/es/sdks/python/error-handling).
</ParamField>

`AsyncClient` implementa el protocolo de administrador de contexto asíncrono (`async with`) para cerrar con éxito la sesión HTTP. `Client` también admite `with`.

## Métodos comunes a ambos clientes.

Todos los métodos aceptan los mismos parámetros con nombre que la conversión [API](/docs/public/es/api/parameters). `AsyncClient` expone la misma firma que `await`.

### `convert_file`

```python theme={null}
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
```

Cargue un archivo local en `POST /convert/raw` con el contenido comprimido en `gzip` si supera 1 MB (transparente, no requiere configuración). Devuelve `str` con Markdown, o `ConversionResult` si `response_format="json"`.

<ParamField body="path" type="str | Path" required>
  Ruta al archivo local.
</ParamField>

<ParamField body="auto_poll" type="boolean" default="true">
  Si el servidor responde `202` (backends saturados), SDK sondea automáticamente desde `GET /jobs/{id}` a `completed` o `failed`. Con `auto_poll=Failedse`, el método convierte `MarkpdfJobQueuedError` con `job_id` para que puedas realizar la encuesta tú mismo. Consulte [Transmisión y asíncrono](/docs/public/es/sdks/python/streaming-and-async).
</ParamField>

### `convert_from_url`

```python theme={null}
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
```

Llame a `POST /convert/from-url`. `url` debe ser un URL prefirmado al que pueda acceder HTTPS.

### `convert_stream`

```python theme={null}
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
```

Devuelve un iterador que produce fragmentos de Markdown a medida que llegan a través de streaming (`POST /convert/stream` o `/convert/stream-from-url` dependiendo de los pases `path` o `url`). Consulte [Transmisión y asíncrono](/docs/public/es/sdks/python/streaming-and-async).

### `pdf_index`

```python theme={null}
client.pdf_index(url: str, *, filename: str | None = None) -> PdfSpine
```

Llame a `POST /pdf/index`. Devuelve un objeto `PdfSpine` escrito con `page_count`, `sections`, `pages`, `font_model`, `estimated_tokens_full`, etc., los mismos campos documentados por [`POST /pdf/index`](/docs/public/es/api/pdf-index).

```python theme={null}
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`

```python theme={null}
client.get_job(job_id: str) -> JobStatus
```

Consulta manualmente `GET /jobs/{id}`. `JobStatus.status` es uno de `"queued"`, `"processing"`, `"completed"`, `"failed"`. Cuando `status == "completed"`, `JobStatus.body` contiene el resultado original (Markdown o JSON según los parámetros de la conversión en cola).

## Tipos de devolución

### `ConversionResult`

<ResponseField name="markdown" type="str">
  Documento convertido.
</ResponseField>

<ResponseField name="filename" type="str">
  Nombre del documento procesado.
</ResponseField>

<ResponseField name="input_format" type="str">
  Formato detectado o forzado.
</ResponseField>

<ResponseField name="engine" type="str">
  Motor que produjo la salida.
</ResponseField>

<ResponseField name="size_bytes" type="int">
  Introduzca el tamaño del documento.
</ResponseField>

<ResponseField name="markdown_bytes" type="int">
  Tamaño de reducción de salida.
</ResponseField>

<ResponseField name="token_saved_estimate" type="int">
  Tokens guardados estimados versus documento sin procesar.
</ResponseField>

<ResponseField name="timings" type="Timings">
  `convert_ms`, `clean_ms`, `total_worker_ms`, `upload_ms`, `total_request_ms`.
</ResponseField>

### `PdfSpine`

<ResponseField name="page_count" type="int" />

<ResponseField name="sections" type="list[Section]">
  Cada `Section` tiene `page`, `level`, `text`.
</ResponseField>

<ResponseField name="pages" type="list[PageInfo]">
  Cada `PageInfo` tiene `page`, `chars`, `first_line`, `headings`.
</ResponseField>

<ResponseField name="pages_truncated" type="bool" />

<ResponseField name="estimated_tokens_full" type="int" />

<ResponseField name="estimated_tokens_spine_only" type="int" />

### `JobStatus`

<ResponseField name="job_id" type="str" />

<ResponseField name="status" type="str">
  `"queued"`, `"processing"`, `"completed"` o `"failed"`.
</ResponseField>

<ResponseField name="body" type="str | dict | None">
  Presente solo cuando `status == "completed"`.
</ResponseField>

<ResponseField name="error" type="str | None">
  Presente solo cuando `status == "failed"`.
</ResponseField>