PDF 相关 API

PDF 相关接口统一前缀为 /api/v1/pdf，提供 PDF 合并、拆分、压缩能力。均需要 multipart/form-data 方式上传文件。

合并 PDF

POST /api/v1/pdf/merge

将多个 PDF 文件按顺序合并为一个 PDF。

请求参数（form-data）

参数	类型	必填	说明
file_name	string	✅	输出文件名（不含扩展名）
pdf_list	file[]	✅	要合并的 PDF 列表（可多个）

请求示例

POST /api/v1/pdf/merge
Content-Type: multipart/form-data

file_name=合并结果
pdf_list=@a.pdf
pdf_list=@b.pdf
pdf_list=@c.pdf

响应示例

{
  "output_path": "D:\\EduAssist\\output\\pdf\\...\\合并结果.pdf"
}

拆分 PDF

POST /api/v1/pdf/split

将单个 PDF 按指定的页码范围拆分成多个 PDF 文件。

请求参数（form-data）

参数	类型	必填	说明
pdf_file	file	✅	要拆分的 PDF 文件
split_ranges_str	string	✅	拆分区间 JSON 字符串

split_ranges_str 格式

一个 JSON 数组，每个元素包含 start 与 end（均为页码，从 1 开始）：

[
  { "start": 1, "end": 3 },
  { "start": 5, "end": 8 }
]

校验规则

• split_ranges_str 必须是合法的 JSON 数组，否则返回 400。
• 数组的每一项必须是字典，且必须包含 start 与 end 键，否则返回 400。

请求示例

POST /api/v1/pdf/split
Content-Type: multipart/form-data

pdf_file=@原文件.pdf
split_ranges_str=[{"start":1,"end":3},{"start":5,"end":8}]

响应示例

{
  "output_path": "D:\\EduAssist\\output\\pdf\\...\\原文件"
}

压缩 PDF

POST /api/v1/pdf/compress

压缩单个 PDF 文件，支持预设方案与高级选项覆盖。

请求参数（form-data）

参数	类型	必填	说明
pdf_file	file	✅	要压缩的 PDF 文件
file_name	string	✅	输出文件名（不含扩展名）
preset	string	❌	压缩预设，默认 moderate
advanced_options	string	❌	高级选项 JSON，覆盖预设值

preset 可选值

值	含义
mild	轻度：质量优先，略微减小体积
moderate	中度：平衡质量与体积（默认）
aggressive	重度：大幅压缩，适合邮件发送
extreme	极度：极致压缩，适合存储空间紧张

advanced_options 格式

一个 JSON 对象，可选字段如下，用于覆盖所选预设中的对应参数：

{
  "stream_level": 3,
  "image_quality": 70,
  "convert_all_to_jpg": true,
  "max_dimension": 1600,
  "remove_metadata": true
}

字段	类型	说明
stream_level	int	流压缩级别（0~3）
image_quality	int	图像质量（JPEG，10~100）
convert_all_to_jpg	bool	是否将所有图片转为 JPG
max_dimension	int	图片最长边像素上限
remove_metadata	bool	是否移除文档信息（作者、标题等）

校验规则

• advanced_options 必须为合法的 JSON 对象，否则返回 400。

请求示例

POST /api/v1/pdf/compress
Content-Type: multipart/form-data

pdf_file=@原文件.pdf
file_name=压缩结果
preset=aggressive
advanced_options={"image_quality":60,"remove_metadata":true}

响应示例

{
  "output_path": "D:\\EduAssist\\output\\pdf\\...\\压缩结果.pdf"
}