用 Python 将扫描 PDF 转为 Markdown，可以把识别、下载和后续文本处理接进同一套程序。PDF Craft 的转换在云端执行：Python 创建任务并上传 PDF，等待处理完成，再下载包含 Markdown 和图片资源的 ZIP。
适合先跑通的入口是官方 Python 示例。它使用固定的单页 PDF，方便验证连接、鉴权和结果下载；处理自己的文件需要调整上传与结果校验。若只想手动转换一份文件，可以直接按网页操作教程完成。
先运行固定样例
准备 Python 3.9 或更高版本，无需安装额外依赖。在 OOMOL Console 创建生产环境 API Key，确认账户有足够点数；运行转换会产生用量，费率见充值页面。
以下命令适用于 Bash 和 Zsh。下载脚本后，通过不回显的输入设置密钥：
curl --fail --show-error --location \
https://pdfcraft.ai/examples/api-quickstart.py \
--output api-quickstart.py
export PDF_CRAFT_API_KEY="$(
python3 -c 'import getpass; print(getpass.getpass("API key: "))'
)"
python3 api-quickstart.py
脚本会保存 pdf-craft-task.json，其中的 uuid 用来找回同一次转换。成功后，结果写入 pdf-craft-result.zip。脚本还会在 Markdown 中检查样例里的固定句子，确认拿到了预期文件。
当前脚本只处理固定样例，没有 --input 参数。接入自己的 PDF 时，需要调整上传来源和结果校验，具体改动见文末。
保存任务 ID，按状态继续处理
PDF 转换包含创建、上传、启动、查询和下载几个阶段。启动请求被接受，只表示服务接下了任务，结果需要在后续查询中取得。
示例的主循环根据任务状态决定下一步：
| 状态 | 程序接下来做什么 |
|---|---|
waiting_for_upload | 获取上传地址，按需上传文件，再提交转换参数 |
running | 等待后再次查询，逐渐延长间隔 |
succeeded | 获取下载链接，读取 ZIP 并保存 |
failed 或 cancelled | 停止，保留错误信息 |
上传已完成时，重新获取上传地址会返回文件的读取地址，不必再次上传。启动时使用 {"output_format":"markdown"}，不指定目标语言，便保留原文语言。需要脚注时，可在自己的程序中按转换参数设置精修。
API Key 只传给 API 请求。向返回的存储地址上传或下载时，不附带 API Key；上传要使用响应中提供的请求头。完整请求顺序见 cURL 分步接入。
超时后继续同一个任务
本地脚本超时或断网，不意味着云端转换失败。保留状态文件，用创建任务时的账户恢复：
python3 api-quickstart.py \
--resume pdf-craft-task.json \
--output pdf-craft-result.zip \
--timeout 1200
--timeout 是本次脚本运行的总等待时间，单位为秒，不是给云端任务重新计时。已有输出文件不会被覆盖，需要时换一个 --output 路径。
如果状态文件只有 creation_unknown、没有 uuid，先通过任务列表确认创建结果，再决定是否重建。已经 failed 的任务也不会因为重复启动而重新执行。不同阶段的恢复方法见任务生命周期。
用 Python 读取 ZIP 里的 Markdown
下载结果后，可以直接查看归档中的文件，不必先把全部内容解压。下面的代码只使用 Python 标准库，列出资源，并预览每份 Markdown 的开头：
from pathlib import Path
from zipfile import ZipFile
result = Path("pdf-craft-result.zip")
with ZipFile(result) as archive:
for item in archive.infolist():
if item.is_dir():
continue
print(f"{item.filename}: {item.file_size} bytes")
if item.filename.lower().endswith(".md"):
with archive.open(item) as source:
preview = source.read(8192).decode("utf-8", errors="replace")
print(preview)
这里最多读取每份 Markdown 开头的 8 KiB，因此较长文档的预览会截断，末尾也可能出现不完整字符。正式处理正文时，按你的文件大小和用途读取完整内容。
如果要在编辑器中打开结果，解压到独立文件夹并保留目录结构。只搬走 .md 文件会让本地图片引用失效，归档和分享时应一起保留对应资源，具体见Markdown 图片资源指南。
接入自己的 PDF 时，改哪些地方
固定样例跑通后，可以沿用任务循环，但要把输入与校验改成自己的业务规则：
- 上传来源：将示例下载
SAMPLE_URL的步骤改为读取你的 PDF，例如用Path("document.pdf").read_bytes()取得字节，再发往本次任务返回的上传地址。大文件应按业务需要规划内存与上传方式。 - 结果校验：示例中的
EXPECTED_TEXT只适用于那份单页 PDF。改为检查 ZIP 中是否有预期的 Markdown，并根据文档需要核对章节或关键内容。 - 任务记录：把输入文件、
uuid和启动参数一并保存。恢复时使用同一份文件和参数；更换已上传文件需要新建任务。 - 大小与时限：示例把单次读取的响应限制为 10 MiB，默认总等待时间为 600 秒。这是示例代码的设置，不是服务的通用文件上限。
从一份真实文档开始，保存原 PDF、任务记录和输出 ZIP，再把读取正文的代码接入笔记整理或其他处理步骤。这样程序中断时能继续原任务，也能随时回到原件检查提取内容。