---
title: "Convert a document to markdown (OCR / parser pipeline)"
method: POST
path: "/v1/ocr/to-markdown"
---

# Convert a document to markdown (OCR / parser pipeline)

`POST /v1/ocr/to-markdown`

## Request

- Base URL: `https://api.clichefactory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.clichefactory.com/v1/ocr/to-markdown`
- Auth: none declared

Convert a document to markdown via VLM (fast) or full parser pipeline (default).

Optional ``Idempotency-Key`` header. The fingerprint covers the
normalized request body (including ``file_uri``, ``mode``, etc.) so
retries that point at the same S3 object with the same options replay
the cached markdown instead of re-running OCR. 24 h TTL.

## Headers

- `Idempotency-Key` string, nullable
- `X-API-KEY` string, nullable

## Request body

- ToMarkdownRequest: Request for OCR / to-markdown conversion.
  - `tenant_id` string: Tenant scope for this operation; must match the authenticated user API key's tenant (e.g. Emio uses str(user.pk)). Admin keys ignore this field.
  - `file_uri` string, required: S3 URI of the file to convert (s3://bucket/key)
  - `file_name` string, nullable: Original filename (used for MIME detection). Inferred from file_uri if omitted.
  - `mode` 'fast' | 'default', nullable: Conversion mode. 'fast' sends file bytes directly to VLM. 'default' (or None) uses the full OCR pipeline.
  - `ocr` ModelEndpointPayload
    - `provider_model` string, nullable
    - `api_key` string, nullable
    - `max_tokens` integer, nullable
    - `temperature` number, nullable
    - `num_retries` integer, nullable
    - `api_base` string, nullable
  - `parsing` ParsingPayload
    - `input_mode` 'markdown' | 'media', nullable
    - `pdf_image_parser` 'docling' | 'docling_vlm' | 'ocr_llm' | 'yolo_per_partes', nullable
    - `pdf_fallback_to_ocr_llm` boolean, nullable
    - `pdf_structured_fallback_to_image` boolean, nullable
    - `pdf_ocr_engine` 'tesseract' | 'rapidocr' | 'easyocr', nullable
    - `pdf_ocr_lang` string, nullable
    - `use_ocr_llm_body` boolean, nullable
    - `image_parser` 'pytesseract' | 'rapidocr' | 'docling' | 'ocr_llm', nullable
    - `image_parser_fallback` boolean, nullable
    - `image_parser_lang` string, nullable

## Response `200`

Successful Response

- ToMarkdownResponse: Response for OCR / to-markdown conversion.
  - `status` string
  - `markdown` string, required: Extracted markdown text
  - `plain_text` string, nullable: Plain text (without markdown formatting)
  - `meta` object: Parser metadata (mode, parser, etc.)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/clichefactory/apis/aio-server.md) · [All operations](https://skmtc.dev/clichefactory/apis/aio-server/llms.txt) · [OpenAPI document](https://skmtc.dev/clichefactory/apis/aio-server/revisions/9bd59f9bbb31?raw)