快速开始

你将完成什么

领取 API 密钥并完成鉴权
发送一次同步解析请求并拿到 md 结果
掌握异步任务的提交与轮询流程
了解常见错误的快速排查方法

获取 API 密钥

前往 SoMark 工作台获取格式为 sk-*** 的 API 密钥。

无需付费购买，获取 API Key 后即可开始使用 API。免费用量规则见免费规则。建议先在测试文档上验证请求参数，再接入生产流程。

选择接口模式

模式	接口	适合场景
同步解析	`POST /parse/sync`	小文件、需要立刻返回结果
异步提交	`POST /parse/async`	大文件、批量处理
异步查询	`POST /parse/async_check`	轮询任务状态并取回结果

调用同步解析（最快上手）

下面示例会上传文件并返回 md + json 两种结果。

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"

读取响应

{
  "code": 0,
  "message": "任务成功",
  "data": {
    "task_id": "a1b2c3d4e5f6",
    "error": null,
    "metadata": {
      "page_num": 10,
      "file_type": ".pdf"
    },
    "result": {
      "file_name": "document.pdf",
      "outputs": {
        "markdown": "# 第一章 引言\n\n本文档介绍了...",
        "json": {
          "pages": [
            {
              "page_num": 0,
              "blocks": [
                {
                  "idx": 0,
                  "type": "title",
                  "bbox": [72, 50, 540, 80],
                  "content": "第一章 引言",
                  "format": "text",
                  "captions": [],
                  "img_url": "",
                  "title_level": 1
                },
                {
                  "idx": 1,
                  "type": "text",
                  "bbox": [72, 100, 540, 200],
                  "content": "本文档介绍了...",
                  "format": "text",
                  "captions": [],
                  "img_url": ""
                }
              ],
              "page_size": { "h": 1684, "w": 1190 },
              "merge_content_from_pre_page": false
            }
          ]
        }
      }
    }
  }
}

当 code 不为 0 时，优先检查 api_key 是否有效、output_formats 是否使用 markdown/json/zip、以及文件是否为空。

异步流程（处理大文件）

调用 POST /parse/async 提交文件，拿到 task_id。
每隔 3~5 秒调用 POST /parse/async_check 查询状态。
当状态为 success 时读取 data.result.outputs。

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"

文档

你将完成什么

下一步

同步解析接口

异步解析接口

文档

​你将完成什么

​下一步

同步解析接口

异步解析接口

你将完成什么

下一步