> ## 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

> Kotlin SDK clases, métodos y opciones.

\#Referencia

## `MarkpdfClient`

```kotlin theme={null}
val client = MarkpdfClient(
    apiKey = "YOUR_API_KEY",
    baseUrl = "https://api.markpdf.tech", // optional, production default
    http = OkHttpClient(),                  // optional, your own OkHttpClient
)
```

<ParamField body="apiKey" type="String" required>
  Tu tecla API.
</ParamField>

<ParamField body="baseUrl" type="String" default="https://api.markpdf.tech">
  URL base de API.
</ParamField>

<ParamField body="http" type="OkHttpClient" default="OkHttpClient()">
  Instancia OkHttp para reutilizar. Útil para compartir el grupo de conexiones con el resto de su aplicación, inyectar interceptores (registro, proxy) o ajustar tiempos de espera.
</ParamField>

`MarkpdfClient` es seguro para subprocesos y está diseñado para crear una instancia una vez y reutilizarse durante toda la vida útil de la aplicación.

## `ConvertOptions`

Clase de datos con valores predeterminados: pase solo lo que desee cambiar.

```kotlin theme={null}
data class ConvertOptions(
    val inputFormat: InputFormat = InputFormat.AUTO,
    val mode: ConversionMode = ConversionMode.FAST,
    val engine: Engine = Engine.AUTO,
    val clean: Boolean = true,
    val imageOcr: Boolean = false,
    val hybridOcr: Boolean = false,
    val responseFormat: ResponseFormat = ResponseFormat.MARKDOWN,
    val slim: Boolean = true,
    val pages: String? = null,
    val outputUrl: String? = null,
    val outputEncoding: OutputEncoding = OutputEncoding.IDENTITY,
    val outputHeadUrl: String? = null,
    val autoPoll: Boolean = true,
)
```

```kotlin theme={null}
// Example: just change mode
val options = ConvertOptions(mode = ConversionMode.BALANCED)
```

### Enumeraciones

```kotlin theme={null}
enum class InputFormat { AUTO, PDF, DOCX, XLSX, PPTX, CSV, TXT, ZIP }
enum class ConversionMode { FAST, ULTRA_FAST, BALANCED, QUALITY, AUTO }
enum class ResponseFormat { MARKDOWN, JSON }
enum class OutputEncoding { IDENTITY, GZIP, ZSTD }
```

Consulte [Modos](/docs/public/es/concepts/modes) y [Formatos](/docs/public/es/concepts/formats).

## Métodos (todos `suspend`)

### `convertFile`

```kotlin theme={null}
suspend fun convertFile(
    file: File,
    options: ConvertOptions = ConvertOptions(),
): ConvertResult
```

Cargue el archivo mediante multiparte a `POST /convert`.

### `convertBytes`

```kotlin theme={null}
suspend fun convertBytes(
    data: ByteArray,
    filename: String,
    options: ConvertOptions = ConvertOptions(),
): ConvertResult
```

Envíe `data` como cuerpo sin formato a `POST /convert/raw`.

### `convertFromUrl`

```kotlin theme={null}
suspend fun convertFromUrl(
    url: String,
    filename: String? = null,
    options: ConvertOptions = ConvertOptions(),
): ConvertResult
```

Llama a `POST /convert/from-url`.

### `pdfIndex`

```kotlin theme={null}
suspend fun pdfIndex(url: String, filename: String? = null): JsonObject
```

Llame a `POST /pdf/index`. Devuelve un `kotlinx.serialization.json.JsonObject` con el lomo: `pageCount`, `sections`, `fontModel`, etc.

```kotlin theme={null}
val spine = client.pdfIndex("https://bucket.example.com/report.pdf?sig=...")
val sections = spine["sections"]!!.jsonArray
for (section in sections) {
    println(section.jsonObject["text"])
}
```

### `getJob`

```kotlin theme={null}
suspend fun getJob(jobId: String): Job
```

Consulta manualmente `GET /jobs/{id}`.

### `waitForJob`

```kotlin theme={null}
suspend fun waitForJob(
    jobId: String,
    pollInterval: Duration = 5.seconds,
    timeout: Duration? = null,
): Job
```

Encuestas desde `GET /jobs/{id}` (usando `kotlinx.coroutines.delay`, sin bloquear el hilo) hasta `completed`/`failed` o hasta que se agote `timeout`. `Duration` es `kotlin.time.Duration`.

## `ConvertResult`

Clase sellada con tres subtipos: utiliza `when` exhaustivo:

```kotlin theme={null}
sealed class ConvertResult {
    data class Markdown(val markdown: String) : ConvertResult()
    data class Json(val result: JsonResult) : ConvertResult()
    data class Queued(val job: Job) : ConvertResult()
}
```

```kotlin theme={null}
val markdown = when (val result = client.convertBytes(bytes, "report.pdf")) {
    is ConvertResult.Markdown -> result.markdown
    is ConvertResult.Json -> result.result.markdown
    is ConvertResult.Queued -> error("job en cola: ${result.job.jobId}")
}
```

## `JsonResult`

```kotlin theme={null}
data class JsonResult(
    val markdown: String,
    val filename: String,
    val inputFormat: String,
    val engine: String,
    val sizeBytes: Long,
    val markdownBytes: Long,
    val tokenSavedEstimate: Long,
    val timings: Timings,
)

data class Timings(
    val convertMs: Long,
    val cleanMs: Long,
    val totalWorkerMs: Long,
    val uploadMs: Long,
    val totalRequestMs: Long,
)
```

## `Job`

```kotlin theme={null}
data class Job(
    val jobId: String,
    val status: JobStatus, // enum: QUEUED, PROCESSING, COMPLETED, FAILED
    val body: JsonElement? = null,
    val error: String? = null,
)
```