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

# SoMark API

> 用最短路径完成 SoMark API 鉴权、同步解析和异步解析。

适合直接调 HTTP 接口、自己控制请求参数、后端流程和结果处理的团队。如果你还在比较接入方式，先看 [入门总览](/documentation/get-started-overview)；如果你要核对鉴权、限制和接口列表，再看 [API 概览](/api-reference/index)。

<Steps>
  <Step title="获取 API Key 并完成调用前检查">
    前往 [somark.tech/workbench/apikey](https://somark.tech/workbench/apikey) 获取 `sk-***` 格式的 API Key。

    调用前只检查三件事：

    * 已传入 `api_key`
    * 文件不为空且格式受支持
    * `output_formats` 只使用 `markdown`、`json`、`zip`

    <Note>
      免费用量规则见 [免费规则](/documentation/free-tier-rules)。
    </Note>
  </Step>

  <Step title="先跑通一次同步解析">
    小文件先走 `POST /parse/sync`。请求发出后，结果会直接在当前响应里返回。

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://somark.tech/api/v1/parse/sync \
        -F "file=@document.pdf" \
        -F "output_formats=markdown" \
        -F "output_formats=json" \
        -F "api_key=sk-your-api-key"
      ```

      ```python Python theme={null}
      import requests

      with open("document.pdf", "rb") as file_obj:
          response = requests.post(
              "https://somark.tech/api/v1/parse/sync",
              files={"file": file_obj},
              data=[
                  ("output_formats", "markdown"),
                  ("output_formats", "json"),
                  ("api_key", "sk-your-api-key"),
              ],
              timeout=120,
          )

      payload = response.json()
      print(payload["data"]["result"]["outputs"]["markdown"])
      ```
    </CodeGroup>
  </Step>

  <Step title="大文件改用异步提交和查询">
    大文件、批处理和后台任务走异步：先调 `POST /parse/async` 拿 `task_id`，再调 `POST /parse/async_check` 轮询状态。

    ```bash theme={null}
    curl -X POST https://somark.tech/api/v1/parse/async \
      -F "file=@large.pdf" \
      -F "output_formats=markdown" \
      -F "api_key=sk-your-api-key"

    curl -X POST https://somark.tech/api/v1/parse/async_check \
      -F "task_id=your-task-id" \
      -F "api_key=sk-your-api-key"
    ```

    <Tip>
      轮询间隔建议保持在 3 到 5 秒。
    </Tip>
  </Step>

  <Step title="继续看详细接口文档">
    * [同步解析接口](/api-reference/endpoint/sync)
    * [异步提交接口](/api-reference/endpoint/async-submit)
    * [异步查询接口](/api-reference/endpoint/async-check)
    * [错误码说明](/api-reference/errors)
  </Step>
</Steps>