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

# 异步解析 — 查询结果

> 根据 task_id 查询异步任务状态和解析结果

使用[提交任务](https://docs.somark.ai/open-source-tools/oxr/async-submit.md)返回的 `task_id`，每 **3–5 秒**查询一次。

按业务需要设置轮询截止时间，下面的 Python 示例使用 120 秒。到时仍未获取结果，保留原 `task_id`，稍后可以继续查询同一任务。

| `data.status` | 含义 |
| - | - |
| `QUEUING` | 等待处理 |
| `PROCESSING` | 解析中 |
| `SUCCESS` | 解析成功，从 `data.result.outputs` 读取结果 |
| `FAILED` | 解析失败，从 `data.error` 查看原因 |


## OpenAPI

````yaml open-source-tools/oxr/openapi.json POST /parse/async_check
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_check:
    post:
      summary: 异步解析 — 查询结果
      operationId: oxrParseAsyncCheck
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - task_id
              properties:
                task_id:
                  type: string
                  description: 提交异步任务后返回的任务 ID。
                  example: 7536c9d4c01341a3855a7deeb591b5ad
                api_key:
                  type: string
                  description: 可选占位值。OXR Free API 不校验此字段。
                  example: dummy
      responses:
        '200':
          description: 返回任务状态，解析成功时一并返回结果。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncCheckResponse'
              examples:
                success:
                  value:
                    code: 0
                    message: 查询成功
                    warnings: []
                    data:
                      task_id: 7536c9d4c01341a3855a7deeb591b5ad
                      status: SUCCESS
                      file_name: example.png
                      result:
                        file_name: example.png
                        outputs:
                          markdown: |
                            # OXR API example

                            This document has one page.
                      metadata:
                        file_type: .png
                        page_num: 1
                        processing_time_ms: 205
                      error: null
                processing:
                  value:
                    code: 0
                    message: 查询成功
                    warnings: []
                    data:
                      task_id: 7536c9d4c01341a3855a7deeb591b5ad
                      status: PROCESSING
                      file_name: example.png
                      result: null
                      metadata: {}
                      error: null
        '404':
          description: 未找到任务。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    code: 1133
                    message: task not found
                    warnings: []
                    data: null
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            curl --fail-with-body
            https://free-oxr.somark.ai/api/v1/parse/async_check \
              -F 'task_id=YOUR_TASK_ID'
        - lang: python
          label: Python
          source: |-
            import time
            import requests

            url = "https://free-oxr.somark.ai/api/v1/parse/async_check"
            task_id = "YOUR_TASK_ID"

            deadline = time.monotonic() + 120

            while (remaining := deadline - time.monotonic()) > 0:
                response = requests.post(url, data={"task_id": task_id}, timeout=min(30, remaining))
                response.raise_for_status()
                body = response.json()
                if body["code"] != 0:
                    raise RuntimeError(body["message"])

                task = body["data"]
                if task["status"] == "SUCCESS":
                    print(task["result"]["outputs"])
                    break
                if task["status"] == "FAILED":
                    raise RuntimeError(task["error"])
                time.sleep(min(3, max(0, deadline - time.monotonic())))
            else:
                raise TimeoutError(f"轮询已超时。保留 task_id={task_id}，稍后继续查询。")
components:
  schemas:
    AsyncCheckResponse:
      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
          properties:
            task_id:
              type: string
              example: 7536c9d4c01341a3855a7deeb591b5ad
            status:
              type: string
              enum:
                - QUEUING
                - PROCESSING
                - SUCCESS
                - FAILED
              example: SUCCESS
            file_name:
              type: string
              example: example.png
              nullable: true
            result:
              $ref: '#/components/schemas/ParseResult'
            metadata:
              $ref: '#/components/schemas/ParseMetadata'
            error:
              type: string
              nullable: true
              description: 解析失败时返回的错误详情。
    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
    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

````

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