> ## 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 或图片，获取后台解析任务的 task_id

上传文件后，从 `data.task_id` 取得任务 ID，再调用[异步解析 — 查询结果](https://docs.somark.ai/open-source-tools/oxr/async-check.md)。上传限制和解析参数与[同步解析](https://docs.somark.ai/open-source-tools/oxr/sync.md)相同。


## OpenAPI

````yaml open-source-tools/oxr/openapi.json POST /parse/async
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/async:
    post:
      summary: 异步解析 — 提交任务
      operationId: oxrParseAsyncSubmit
      requestBody:
        $ref: '#/components/requestBodies/ParseUpload'
      responses:
        '200':
          description: 返回任务 ID 和初始状态，或返回 API 错误。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncSubmitResponse'
              examples:
                success:
                  value:
                    code: 0
                    message: 任务已提交
                    warnings: []
                    data:
                      task_id: 7536c9d4c01341a3855a7deeb591b5ad
                      status: QUEUING
                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/async
            \
              -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/async"
            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"]["task_id"])
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:
    AsyncSubmitResponse:
      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
            status:
              type: string
              enum:
                - QUEUING
    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
    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.