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

# 同步转换

> 上传 PDF，并在解析和转换完成后直接获取 Office 文件下载地址

该接口会依次完成 PDF 解析和 Office 文件生成，并保持连接直到任务成功、失败或超时。成功时，响应中的 `download_url` 是短期有效的下载地址。

### 转换参数

| 参数            | 可选值               | 默认值                          | 说明                                             |
| ------------- | ----------------- | ---------------------------- | ---------------------------------------------- |
| `target_type` | `word` / `ppt`    | `word`                       | 指定 PDF 的转换目标格式。Word 来源选择 `word`，PPT 来源选择 `ppt` |
| `layout_mode` | `flow` / `layout` | Word 为 `flow`；PPT 为 `layout` | `flow` 表示流式重排，`layout` 表示版面还原                  |

<Note>
  * 请根据 PDF 的原始文件类型选择 `target_type`：由 Word 导出的 PDF 选择 `word`，由 PPT 导出的 PDF 选择 `ppt`。选择错误可能影响内容结构和版式还原效果。
  * 当 `target_type` 为 `ppt` 时，`layout_mode` 只能是 `layout`；`ppt` 与 `flow` 的组合会被拒绝。
  * 仅支持 PDF 文件，单文件最大 **200MB**、最多 **300 页**。`file` 与 `file_url` 必须且只能提供一项；处理时间较长或需要批量转换时，建议使用 [异步转换](/api-reference/endpoint/pdf2office-async-submit)。
</Note>


## OpenAPI

````yaml POST /pdf2office/sync
openapi: 3.0.3
info:
  title: SoMark 文档智能 API
  description: SoMark 文档智能 API，支持 PDF、图片、Word、PPT 和 Excel 文件解析，以及 PDF 转 Word/PPT。
  version: 1.0.0
servers:
  - url: https://somark.cn/api/v1
security: []
paths:
  /pdf2office/sync:
    post:
      summary: PDF 转 Office — 同步转换
      description: 上传 PDF，同步等待解析和 Office 转换完成。成功后返回短期有效的下载地址。
      operationId: pdf2officeSync
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Pdf2OfficeSubmitRequest'
      responses:
        '200':
          description: 转换完成或任务失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pdf2OfficeResponse'
      x-codeSamples:
        - lang: python
          label: Python
          source: |-
            import requests

            url = "https://somark.cn/api/v1/pdf2office/sync"

            data = {
                "api_key": "sk-***",
                "target_type": "word",
                "layout_mode": "flow",
            }

            with open("example.pdf", "rb") as file:
                response = requests.post(url, data=data, files={"file": file})

            result = response.json()
            print(result["data"].get("download_url"))
        - lang: bash
          label: cURL
          source: |-
            curl -X POST https://somark.cn/api/v1/pdf2office/sync \
              -F "file=@example.pdf" \
              -F "api_key=sk-***" \
              -F "target_type=word" \
              -F "layout_mode=flow"
components:
  schemas:
    Pdf2OfficeSubmitRequest:
      type: object
      required:
        - api_key
      properties:
        file:
          type: string
          format: binary
          description: PDF 文件，与 file_url 二选一；最大 200MB、300 页
        file_url:
          type: string
          format: uri
          description: PDF 的公开或有效预签名下载链接，与 file 二选一
        api_key:
          type: string
          description: API 密钥，格式 sk-***
          example: sk-***
        target_type:
          type: string
          enum:
            - word
            - ppt
          default: word
          description: >-
            目标文件类型。请根据 PDF 的原始文件类型选择：由 Word 导出的 PDF 选择 word，由 PPT 导出的 PDF 选择
            ppt。选择错误可能影响内容结构和版式还原效果
        layout_mode:
          type: string
          nullable: true
          enum:
            - flow
            - layout
          description: 排版模式。Word 未传时默认 flow；PPT 未传时默认 layout，且 PPT 仅支持 layout
    Pdf2OfficeResponse:
      type: object
      properties:
        code:
          type: integer
          description: 状态码，0 为成功，非 0 见错误码说明
          example: 0
        message:
          type: string
          example: 查询成功
        data:
          type: object
          properties:
            task_id:
              type: string
              description: 任务 ID
              example: c5e6c983f28a4e6eb5d6c061343a8642
            status:
              type: string
              description: 任务状态
              enum:
                - parsing
                - queued
                - converting
                - succeeded
                - failed
              example: succeeded
            target_type:
              type: string
              enum:
                - word
                - ppt
              example: word
            layout_mode:
              type: string
              enum:
                - flow
                - layout
              example: flow
            file_name:
              type: string
              description: 原始 PDF 文件名
              example: document.pdf
            page_num:
              type: integer
              description: PDF 页数
              example: 12
            result_file_name:
              type: string
              nullable: true
              description: 转换结果文件名
              example: document.docx
            error_code:
              type: integer
              nullable: true
              description: 任务失败错误码，成功时为 null
              example: null
            error_message:
              type: string
              nullable: true
              description: 任务失败原因，成功时为 null
              example: null
            created_at:
              type: string
              nullable: true
              description: 任务创建时间，ISO 8601 格式
            started_at:
              type: string
              nullable: true
              description: 转换开始时间，ISO 8601 格式
            finished_at:
              type: string
              nullable: true
              description: 任务完成时间，ISO 8601 格式
            download_url:
              type: string
              format: uri
              description: 结果文件的短期签名下载地址，仅 succeeded 状态返回
              example: https://example.com/result.docx?signature=***
            expires_in:
              type: integer
              description: download_url 有效期，单位为秒
              example: 1800
      example:
        code: 0
        message: 查询成功
        data:
          task_id: c5e6c983f28a4e6eb5d6c061343a8642
          status: succeeded
          target_type: word
          layout_mode: flow
          file_name: document.pdf
          page_num: 12
          result_file_name: document.docx
          error_code: null
          error_message: null
          created_at: '2026-08-24T10:00:00'
          started_at: '2026-08-24T10:00:10'
          finished_at: '2026-08-24T10:01:20'
          download_url: https://example.com/result.docx?signature=***
          expires_in: 1800

````