Parsing

Use parsing when you need the document itself rather than a predefined set of fields. The openparser@1 response includes plain text, Markdown, pages, elements, relations, text annotations, and assets.

See the OpenParser schema for the complete response contract and field definitions.

Send the document

For a one-off document, upload its bytes in the multipart file field. If you plan to process the same document more than once, upload it with POST /files and pass the returned file_id:

curl -X POST 'https://api.openparser.dev/parse/async' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || openssl rand -hex 16)" \
  -F 'request={"ocr_model":"paddleocr-vl-1.6","file_id":"FILE_ID"};type=application/json'

openparser parse async --file-id FILE_ID --ocr-model paddleocr-vl-1.6

const accepted = await client.parse.async({
  ocr_model: 'paddleocr-vl-1.6',
  file_id: 'FILE_ID',
});

accepted = client.parse.async_({
    "ocr_model": "paddleocr-vl-1.6",
    "file_id": "FILE_ID",
})

Each request accepts one source: either file or file_id.

Choose a model

Set ocr_model to an ID returned by GET /models/ocr. The current public model is paddleocr-vl-1.6.

The model registry also lists supported options. At present, these are image_block_ocr, chart_recognition, and merge_layout_blocks. Unsupported models or options return 422 Unprocessable Content before work starts.

merge_layout_blocks defaults to false, keeping recognized text aligned with each detected element bounding box. Set it to true when you prefer PaddleOCR-VL's merged recognition behavior and do not require one-to-one text geometry:

{
  "ocr_model": "paddleocr-vl-1.6",
  "ocr_options": {
    "merge_layout_blocks": true
  }
}

When enabled, PaddleOCR-VL may combine text from nearby regions into the first element and leave the remaining merged elements empty.

Choose an output format

Use openparser@1 for new integrations. Choose raw only when you need fields specific to the OCR provider.

Sync vs async

Use /parse when holding the connection open is convenient. Use /parse/async for queues, webhooks, or any service that prefers to poll. All three endpoints require an Idempotency-Key.

The synchronous endpoint can still return 202 when the wait window expires. In that case, poll the job URL from the Location header.

Billing

Parsing costs $0.001 per successfully parsed page. Failed and indeterminate jobs have no page charge.

Related

• OpenParser schema
• Extraction
• Batching
• Errors and retries