本页路径均相对于 https://api.pdfcraft.ai/v1/pcc-api。每次 API 请求携带 Authorization: Bearer YOUR_API_KEY，JSON 请求体使用 Content-Type: application/json。响应为 JSON，请勿缓存。接口定义也可下载为 OpenAPI。
创建任务
POST /transforms
| JSON 字段 | 必填 | 说明 |
|---|---|---|
input_format | 是 | pdf 或 epub，创建后不可修改 |
input_filename | 否 | 展示名称，1–255 个 Unicode 码点，不能全为空白；禁止控制字符和非法代理字符 |
未知字段会被拒绝。创建时 input_filename 不接受 null；它不决定下载名称或存储位置。
{ "input_format": "pdf", "input_filename": "document.pdf"}创建成功后返回 201，响应中包含任务信息。请保存 uuid，上传时会用到。过期时间以实际响应为准。
{ "uuid": "8ae07e41-6e94-4144-9562-5af4116cba7e", "input_format": "pdf", "input_filename": "document.pdf", "status": "waiting_for_upload", "created_at": "2026-10-29T08:00:00.000Z", "updated_at": "2026-10-29T08:00:00.000Z", "expires_at": "2026-10-29T09:00:00.000Z"}查询任务
GET /transforms/{uuid} 返回 200 和任务信息。
| 响应字段 | 出现条件 | 说明 |
|---|---|---|
uuid、input_format、status | 始终 | 任务标识、输入格式、生命周期状态 |
created_at、updated_at | 始终 | ISO 8601 时间 |
parameters | 启动被接受后 | 规范化且不可变的启动参数 |
finished_at、expires_at | 可用时 | 完成时间及服务决定的过期时间 |
input_filename | 已提供且未清除 | 原文件展示名称 |
title、authors、language | 已提取并保存时 | 原文档元数据；authors 是姓名数组，language 不保证使用 API 目标语言代码 |
statistics | 可用时 | processed_pages 和／或 processed_words，不是费用或实时百分比 |
error | 已记录错误时 | 含 code 与 message 的对象 |
可选字段可能缺失。通过此接口读取状态，详细实时进度使用 observation。无权限、不存在或过期的任务返回 404。
修改原文件展示名称
PATCH /transforms/{uuid}
此接口只接受 input_filename，名称要求与创建任务时相同。传入 null 可清除名称，省略该字段则保持原值。
只要任务仍可访问，无论处于哪个状态，都可以改名。成功后返回 200 和更新后的任务信息。
{ "input_filename": "research.pdf"}改名不会替换已上传文件、修改转换参数或设置下载文件名。
获取上传地址
GET /transforms/{uuid}/upload-urls
返回 200。原文件尚未上传且任务尚未启动时：
{ "put_url": "https://storage.example/source.pdf?signed", "headers": { "Content-Type": "application/pdf", "x-oss-forbid-overwrite": "true" }}向 put_url 发送 PUT 请求，请求体为文件原始内容，并带上返回的请求头，无需传入 API Key。EPUB 文件的 Content-Type 为 application/epub+zip。
文件已上传时，返回的是原文件的读取地址：
{ "get_url": "https://storage.example/source.pdf?signed-get", "head_url": "https://storage.example/source.pdf?signed-head"}已上传的原文件不能覆盖。上述地址用于读取原文件，转换结果需通过下载接口获取。本页中的示例链接无法用于实际请求。
启动处理
POST /transforms/{uuid}/launch
| JSON 字段 | 必填 | 取值／默认值 |
|---|---|---|
output_format | 是 | markdown、epub、pdf |
target_language | 翻译时必填；EPUB 输入或 PDF 输出必须翻译 | 支持列表中的区分大小写代码 |
rendering_mode | 否 | 不翻译默认 source；翻译默认 replace；支持时可用 bilingual 或 bilingual-inline |
translation_prompt | 否 | 非空字符串，仅翻译时允许 |
footnotes | 否，仅 PDF | disabled（默认）、basic、refined |
参见有效组合与语言代码。
{ "output_format": "epub", "target_language": "en", "rendering_mode": "bilingual"}首次接受启动请求时返回 202。重复提交相同的规范化参数时返回 200，两种响应都包含完整的任务信息。
尚未上传文件、已达到并发上限或试图更改启动参数时，返回 409。具体原因由 error.code 区分，见错误处理。
下载结果
GET /transforms/{uuid}/download-urls
任务状态为 succeeded 时，返回 200 和 {get_url, head_url}；其他状态返回 404。
下载文件使用 get_url，通过 HEAD 查看文件信息则使用 head_url。两个地址不能混用，这些请求也无需传入 API Key。
可选查询参数 filename 设置包含扩展名的下载名称。只进行一次 URL 编码：
curl --fail-with-body --silent --show-error --get \ "$BASE/transforms/$TASK_UUID/download-urls" \ -H "Authorization: Bearer $PDF_CRAFT_API_KEY" \ --data-urlencode 'filename=research.markdown.zip'名称不能全为空白，最多 255 个 UTF-8 字节；禁止控制字符、非法代理字符、/、\，不能是 . 或 ..。无效或重复的 filename 参数返回 400。下载名称仅对本次生成的链接有效，不会保存到任务中，也不会改变文件内容。请自行填写扩展名：Markdown 结果使用 .zip，EPUB 使用 .epub，PDF 使用 .pdf。获取链接后应原样使用，不能直接修改其中的文件名。
查询任务列表
| 接口 | 内容 | 排序 |
|---|---|---|
GET /transforms/waiting-for-upload/ | 尚未启动的任务，包括已上传文件 | 创建时间倒序 |
GET /transforms/running/ | 启动已接受的任务，包括排队任务 | 创建时间正序 |
GET /transforms/finished/ | 成功、失败、已取消 | 完成时间倒序 |
均接受 limit（1–100，默认 50）及 cursor，时间相同时按 UUID 排序。cursor 原样传回，不能用于其他列表。
{ "transforms": [ { "uuid": "8ae07e41-6e94-4144-9562-5af4116cba7e", "input_format": "pdf", "input_filename": "document.pdf", "status": "waiting_for_upload", "created_at": "2026-10-29T08:00:00.000Z", "updated_at": "2026-10-29T08:00:00.000Z", "expires_at": "2026-10-29T09:00:00.000Z" } ], "next_cursor": "opaque-cursor"}示例为等待上传列表项。最后一页省略 next_cursor。列表只返回基本任务信息，不包含处理进度或下载链接。过期任务不再显示，见保留策略。
获取进度与预览
GET /transforms/{uuid}/observation 接受可选的 cursor 和正整数 preview_limit（默认 500，大于 500 时按 500）。返回 200，包含 status、preview，以及运行中的可选 progress、成功时的 download_urls。
GET /transforms/{uuid}/preview-assets/{stage}/{asset} 返回预览资源的 {get_url, head_url}。stage 为 extraction 或 converting；asset 为 64 位小写十六进制哈希加 .png 或 .pdf。
这些接口不提供完整文档归档。字节范围、cursor 更新和内容格式见进度与预览。