cURL 分步接入

上传自己的 PDF，逐步检查创建、上传、启动和下载请求。

准备一份较小的 PDF，命名为 document.pdf。运行示例需要 Bash 或 Zsh、cURL 7.76 及以上版本、Python 3 和 jq，转换会消耗账户 credits。

请在同一个终端会话中依次执行命令。如果某一步失败，解决后再继续。

准备凭据

在 OOMOL Console 创建密钥后设置：

bash

export PDF_CRAFT_API_KEY="$(  python3 -c 'import getpass; print(getpass.getpass("API key: "))')"BASE=https://api.pdfcraft.ai/v1/pcc-api

Python 命令用于读取密钥，输入时不会显示在终端中。后续请求均使用 cURL。

这些 API 请求带有密钥，因此未添加自动跟随重定向的 --location。如果收到重定向响应，请先检查请求地址。

创建任务

bash

curl --fail-with-body --silent --show-error "$BASE/transforms" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY" \  -H 'Content-Type: application/json' \  --data '{"input_format":"pdf","input_filename":"document.pdf"}' \  --output task.jsonTASK_UUID=$(jq -er '.uuid' task.json)

创建成功后返回 HTTP 201，任务状态为 waiting_for_upload，此时尚未开始转换。task.json 中保存了任务 ID，后续请求会用到。

如果没有收到响应，请先检查等待上传列表，确认任务是否已经创建。

上传文件

bash

curl --fail-with-body --silent --show-error \  "$BASE/transforms/$TASK_UUID/upload-urls" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY" \  --output upload.jsonjq . upload.json

响应中有 put_url 时，向该地址上传文件，并带上 headers 中的全部请求头。本例返回 Content-Type 和 x-oss-forbid-overwrite：

bash

curl --fail-with-body --silent --show-error \  --request PUT "$(jq -er '.put_url' upload.json)" \  -H "Content-Type: $(jq -er '.headers["Content-Type"]' upload.json)" \  -H "x-oss-forbid-overwrite: $(jq -er '.headers["x-oss-forbid-overwrite"]' upload.json)" \  --data-binary @document.pdf

上传文件时无需传入 API Key。如果返回的是 get_url 和 head_url，说明文件已经上传，可以直接进入下一步。

已上传的文件不能覆盖。如果还没上传文件，上传链接就已过期，重新获取链接即可。

启动转换

bash

curl --fail-with-body --silent --show-error \  "$BASE/transforms/$TASK_UUID/launch" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY" \  -H 'Content-Type: application/json' \  --data '{"output_format":"markdown"}'

服务接受启动请求后返回 202。重复提交相同参数会返回 200，不会再次执行转换；此时更换参数则返回 409。翻译或 EPUB 输出的配置见转换参数。

查询状态

bash

curl --fail-with-body --silent --show-error \  "$BASE/transforms/$TASK_UUID" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY"

状态为 running 时，稍后再查询。集成到程序中时，可以参考 Python 示例，逐渐延长查询间隔，并设置总超时时间。

状态变为 succeeded、failed 或 cancelled 后停止查询。失败原因见 error.code，重复调用 launch 不会重启任务。如需展示处理进度，参见进度与预览。

成功后下载

仅在 status 为 succeeded 后执行：

bash

curl --fail-with-body --silent --show-error \  "$BASE/transforms/$TASK_UUID/download-urls" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY" \  --output download.jsoncurl --fail --silent --show-error \  "$(jq -er '.get_url' download.json)" \  --output result.markdown.zip

下载文件时无需传入 API Key。若要用 HEAD 请求查看文件信息，请使用 head_url。

下载链接过期后可以重新获取，但任务过期后文件将无法下载，请及时保存。