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

# 同步解析

> 上传 PDF 或图片，在同一次请求中获取解析结果

解析完成后，从 `data.result.outputs` 读取 Markdown 或 JSON。请直接上传文件，单次最多 **10 MB、20 页**。Free OXR API 无需鉴权，可省略 `api_key`。

有关元素格式和解析选项，请参阅 [SoMark与OXR接入差异](https://docs.somark.ai/open-source-tools/oxr/integration)。如果希望在后台等待结果，请[提交异步任务](https://docs.somark.ai/open-source-tools/oxr/async-submit.md)。


## OpenAPI

````yaml open-source-tools/oxr/openapi.json POST /parse/sync
openapi: 3.0.3
info:
  title: OXR Free API
  version: 1.0.0
  description: 将 PDF 和图片解析为 Markdown 和包含版面信息的 JSON。
servers:
  - url: https://free-oxr.somark.ai/api/v1
security: []
paths:
  /parse/sync:
    post:
      summary: 同步解析
      operationId: oxrParseSync
      requestBody:
        $ref: '#/components/requestBodies/ParseUpload'
      responses:
        '200':
          description: 返回解析结果或 API 错误。
          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 表示成功。即使 HTTP 状态码为 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: 解析失败时返回的错误详情。
    ParseRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: 上传待解析的 PDF、PNG、JPG、JPEG、BMP、TIF、TIFF 或 WebP 文件。单文件最多 10 MB、20 页。
        output_formats:
          type: array
          items:
            type: string
            enum:
              - markdown
              - json
          default:
            - markdown
            - json
          description: 每种输出格式分别作为一个同名表单字段提交。
        api_key:
          type: string
          description: 可选占位值。OXR Free API 不校验此字段。
          example: dummy
        element_formats:
          type: object
          description: 控制各类元素的输出格式。将配置序列化为 JSON 后作为一个表单字段提交。
          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: 解析选项。将配置序列化为 JSON 后作为一个表单字段提交。
          properties:
            keep_header_footer:
              type: boolean
              default: false
        extra:
          type: object
          description: 模型采样参数。将配置序列化为 JSON 后作为一个表单字段提交。
          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 输出时返回的文本。
            json:
              type: object
              description: 请求 JSON 输出时返回的版面结构数据。
              properties:
                pages:
                  type: array
                  items:
                    type: object
                    properties:
                      page_num:
                        type: integer
                        example: 0
                        description: 从 0 开始的页索引。
                      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: 版面元素类型，区分大小写。
                              example: Title
                            bbox:
                              type: array
                              items:
                                type: number
                              minItems: 4
                              maxItems: 4
                              description: 版面元素的边界框坐标，顺序为 [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: 文档总页数。
        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: 请求缺少文件，或上传的文件无效。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            error:
              value:
                code: 1133
                message: a file upload is required
                warnings: []
                data: null
    TaskInProgress:
      description: 已有任务在处理，请等待任务结束后再提交。
      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.