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

# Sync parsing

> Upload a PDF or image and get the parsing result in the same request

When parsing finishes, read the Markdown or JSON from `data.result.outputs`. Upload your file directly, up to **10 MB and 20 pages** per request. The Free OXR API requires no authentication, so you can omit `api_key`.

See [SoMark and OXR integration differences](https://docs.somark.ai/en/open-source-tools/oxr/integration) for element formats and parsing options. To process the file in the background, [submit an async task](https://docs.somark.ai/en/open-source-tools/oxr/async-submit.md).


## OpenAPI

````yaml en/open-source-tools/oxr/openapi.json POST /parse/sync
openapi: 3.0.3
info:
  title: OXR Free API
  version: 1.0.0
  description: Parse PDFs and images into Markdown and layout JSON.
servers:
  - url: https://free-oxr.somark.ai/api/v1
security: []
paths:
  /parse/sync:
    post:
      summary: Sync parsing
      operationId: oxrParseSync
      requestBody:
        $ref: '#/components/requestBodies/ParseUpload'
      responses:
        '200':
          description: Parsing result or API error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncParseResponse'
              examples:
                success:
                  value:
                    code: 0
                    message: 任务成功
                    warnings: []
                    data:
                      task_id: 7536c9d4c01341a3855a7deeb591b5ad
                      error: null
                      result:
                        file_name: example.png
                        outputs:
                          markdown: |
                            # OXR API example

                            This document has one page.
                          json:
                            pages:
                              - page_num: 0
                                page_size:
                                  h: 225
                                  w: 770
                                merge_content_from_pre_page: false
                                blocks:
                                  - idx: 1
                                    type: Title
                                    bbox:
                                      - 41.31
                                      - 57.67
                                      - 389.58
                                      - 104.5
                                    content: OXR API example
                                    format: text
                                  - idx: 2
                                    type: Text
                                    bbox:
                                      - 41.39
                                      - 125.45
                                      - 417.2
                                      - 160.12
                                    content: This document has one page.
                                    format: text
                      metadata:
                        file_type: .png
                        page_num: 1
                        processing_time_ms: 205
                invalidParameter:
                  $ref: '#/components/examples/UnsupportedOutputFormat'
        '400':
          $ref: '#/components/responses/InvalidUpload'
        '429':
          $ref: '#/components/responses/TaskInProgress'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body https://free-oxr.somark.ai/api/v1/parse/sync \
              -F 'file=@document.pdf' \
              -F 'output_formats=markdown' \
              -F 'output_formats=json'
        - lang: python
          label: Python
          source: |-
            import requests

            url = "https://free-oxr.somark.ai/api/v1/parse/sync"
            with open("document.pdf", "rb") as document:
                response = requests.post(
                    url,
                    files={"file": document},
                    data=[("output_formats", "markdown"), ("output_formats", "json")],
                    timeout=60,
                )
            response.raise_for_status()
            body = response.json()
            if body["code"] != 0:
                raise RuntimeError(body["message"])
            print(body["data"]["result"]["outputs"])
components:
  requestBodies:
    ParseUpload:
      required: true
      content:
        multipart/form-data:
          schema:
            $ref: '#/components/schemas/ParseRequest'
          encoding:
            output_formats:
              style: form
              explode: true
            element_formats:
              contentType: application/json
            feature_config:
              contentType: application/json
            extra:
              contentType: application/json
  schemas:
    SyncParseResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
          description: >-
            0 indicates success. Check this field even if the HTTP status is
            200.
        message:
          type: string
          example: 任务成功
        warnings:
          type: array
          items:
            type: string
          example: []
        data:
          type: object
          nullable: true
          properties:
            task_id:
              type: string
              example: 7536c9d4c01341a3855a7deeb591b5ad
            result:
              $ref: '#/components/schemas/ParseResult'
            metadata:
              $ref: '#/components/schemas/ParseMetadata'
            error:
              type: string
              nullable: true
              description: Error details when parsing fails.
    ParseRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: >-
            PDF, PNG, JPG, JPEG, BMP, TIF, TIFF, or WebP upload. Up to 10 MB and
            20 pages.
        output_formats:
          type: array
          items:
            type: string
            enum:
              - markdown
              - json
          default:
            - markdown
            - json
          description: Send one form field per format.
        api_key:
          type: string
          description: Optional placeholder. The Free API does not validate this field.
          example: dummy
        element_formats:
          type: object
          description: Element output formats. Encode as a JSON object in one form field.
          properties:
            image:
              type: string
              enum:
                - url
                - base64
                - none
              default: url
            formula:
              type: string
              enum:
                - latex
              default: latex
            table:
              type: string
              enum:
                - html
                - markdown
              default: html
            cs:
              type: string
              enum:
                - smiles
                - image
              default: smiles
        feature_config:
          type: object
          description: Parsing options. Encode as a JSON object in one form field.
          properties:
            keep_header_footer:
              type: boolean
              default: false
        extra:
          type: object
          description: Model sampling options. Encode as a JSON object in one form field.
          properties:
            temperature:
              type: number
              minimum: 0
              maximum: 2
            top_p:
              type: number
              minimum: 0
              maximum: 1
            repetition_penalty:
              type: number
              minimum: 0
              exclusiveMinimum: true
    ParseResult:
      type: object
      nullable: true
      properties:
        file_name:
          type: string
          example: example.png
        outputs:
          type: object
          properties:
            markdown:
              type: string
              description: Markdown text, returned when requested.
            json:
              type: object
              description: Layout JSON, returned when requested.
              properties:
                pages:
                  type: array
                  items:
                    type: object
                    properties:
                      page_num:
                        type: integer
                        example: 0
                        description: Zero-based page index.
                      page_size:
                        type: object
                        properties:
                          h:
                            type: integer
                            example: 225
                          w:
                            type: integer
                            example: 770
                      merge_content_from_pre_page:
                        type: boolean
                      blocks:
                        type: array
                        items:
                          type: object
                          additionalProperties: true
                          properties:
                            idx:
                              type: integer
                              example: 1
                            type:
                              type: string
                              description: Case-sensitive layout block type.
                              example: Title
                            bbox:
                              type: array
                              items:
                                type: number
                              minItems: 4
                              maxItems: 4
                              description: Bounding box as [x_min, y_min, x_max, y_max].
                              example:
                                - 41.31
                                - 57.67
                                - 389.58
                                - 104.5
                            content:
                              type: string
                              example: OXR API example
                            format:
                              type: string
                              example: text
    ParseMetadata:
      type: object
      properties:
        file_type:
          type: string
          example: .png
        page_num:
          type: integer
          example: 1
          description: Number of pages.
        processing_time_ms:
          type: integer
          example: 205
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 1133
        message:
          type: string
          example: task not found
        warnings:
          type: array
          items:
            type: string
          example: []
        data:
          type: object
          nullable: true
          example: null
  examples:
    UnsupportedOutputFormat:
      value:
        code: 1133
        message: >-
          参数错误: output_formats=zip is not supported by open-source OXR; zip
          packaging is not implemented.
        warnings: []
        data: null
  responses:
    InvalidUpload:
      description: The request is missing a file or the upload is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            error:
              value:
                code: 1133
                message: a file upload is required
                warnings: []
                data: null
    TaskInProgress:
      description: >-
        A task is already in progress. Wait for it to finish before submitting
        another.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            error:
              value:
                code: 1133
                message: >-
                  A task is already in progress. Please wait for it to finish,
                  then try again.
                warnings: []
                data: null

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.