> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# Async parsing — Submit Task
> Submit a file parsing task and immediately receive a task_id; the document is processed in the background
Path change: This endpoint path has been changed from `/extract/async` to `/parse/async`. The old path will be discontinued on December 31, 2026. Please migrate to the new path before then.
Parameter change: `extract_config` has been renamed to `feature_config`. Please replace `extract_config` with `feature_config` in your requests.
Async parsing requires both endpoints. Calling the submit endpoint alone does not return the final parsing result.
1. Call this endpoint to submit the task. It immediately returns a `task_id`.
2. Use that `task_id` to poll the [result query](/en/api-reference/endpoint/async-check) endpoint.
3. Read the parsing result from the result query endpoint after the task status becomes `SUCCESS`. The recommended polling interval is **3\~5 seconds**.
The parameter definitions for `output_formats`, `element_formats`, and `feature_config` are the same as in [Sync parsing](/en/api-reference/endpoint/sync); if you want the auth and limits summary, go back to the [API overview](/en/api-reference/index).
## OpenAPI
````yaml POST /parse/async
openapi: 3.0.3
info:
title: SoMark 文档智能 API
description: >-
SoMark 文档解析服务 API，支持 PDF、图片、Word、PPT 和 Excel 文件解析，输出 Markdown / JSON / DOCX
格式。
version: 1.0.0
servers:
- url: https://somark.cn/api/v1
security: []
paths:
/parse/async:
post:
summary: 异步解析 — 提交任务
description: 提交文件解析任务，立即返回 task_id，文档在后台处理。
operationId: parseAsyncSubmit
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- api_key
properties:
file:
type: string
format: binary
description: 待解析的文件，支持 PDF、图片、Word、PPT 和 Excel 格式
output_formats:
type: array
items:
type: string
enum:
- json
- markdown
- zip
default:
- markdown
- json
description: >-
输出格式，可多选。不传时默认为 ["markdown", "json"]。支持 json / markdown /
zip，其中 zip 将所有输出文件打包为压缩包
api_key:
type: string
description: API 密钥，格式 sk-***
element_formats:
type: object
description: 元素格式配置，控制各类元素的输出格式
properties:
image:
type: string
enum:
- url
- base64
- none
default: url
description: 图片返回方式
formula:
type: string
enum:
- latex
- mathml
- ascii
default: latex
description: 公式格式
table:
type: string
enum:
- markdown
- html
- image
default: html
description: 表格格式
cs:
type: string
enum:
- image
default: image
description: 化学结构式格式
feature_config:
type: object
description: 特色功能配置（参数已从 extract_config 更名为 feature_config）
properties:
enable_text_cross_page:
type: boolean
default: false
description: 文字跨页拼接
enable_table_cross_page:
type: boolean
default: false
description: 表格跨页拼接
enable_title_level_recognition:
type: boolean
default: false
description: 标题层级识别
enable_inline_image:
type: boolean
default: false
description: 返回文中图
enable_table_image:
type: boolean
default: true
description: 返回表中图
enable_image_understanding:
type: boolean
default: true
description: 图片理解
keep_header_footer:
type: boolean
default: false
description: 保留页眉页脚
responses:
'200':
description: 任务提交成功
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncSubmitResponse'
x-codeSamples:
- lang: python
label: Python
source: |-
import json
import requests
url = "https://somark.cn/api/v1/parse/async"
data = {
"output_formats": ["markdown", "json"],
"api_key": "sk-***",
"element_formats": json.dumps({
"image": "url",
"formula": "latex",
"table": "html",
"cs": "image",
}),
"feature_config": json.dumps({
"enable_text_cross_page": False,
"enable_table_cross_page": False,
"enable_title_level_recognition": False,
"enable_inline_image": False,
"enable_table_image": True,
"enable_image_understanding": True,
"keep_header_footer": False,
}),
}
files = {"file": ("example.pdf", open("example.pdf", "rb"))}
response = requests.post(url, data=data, files=files)
task_id = response.json()["data"]["task_id"]
print(f"任务已提交，task_id: {task_id}")
- lang: bash
label: cURL
source: |-
curl -X POST https://somark.cn/api/v1/parse/async \
-F "file=@example.pdf" \
-F "output_formats=markdown" \
-F "output_formats=json" \
-F "api_key=sk-***" \
-F 'element_formats={"image":"url","formula":"latex","table":"html","cs":"image"}' \
-F 'feature_config={"enable_text_cross_page":false,"enable_table_cross_page":false,"enable_title_level_recognition":false,"enable_inline_image":false,"enable_table_image":true,"enable_image_understanding":true,"keep_header_footer":false}'
components:
schemas:
AsyncSubmitResponse:
type: object
properties:
code:
type: integer
description: 状态码，`0` 为成功，非 `0` 见[错误码](/api-reference/errors)
example: 0
message:
type: string
example: 任务已提交
data:
type: object
properties:
task_id:
type: string
description: 任务 ID，用于后续轮询
example: c5e6c983f28a4e6eb5d6c061343a8642
status:
type: string
description: 初始状态，固定为 QUEUING
example: QUEUING
````