PDF文档转换返回字段全解：state 状态机与 task_id 生命周期

# PDF文档转换返回字段全解：state 状态机与 task_id 生命周期 > 接口：PDF文档转换 · 接入点 `3275-1` / `3275-2` · 付费 · POST/GET · JSON > 适用人群：中高级开发者、对接过异步接口的工程师 > 阅读时间：约 5 分钟 > 最后实测核对：2026-09-07 --- ## 核心要点 - 接口返回的是 `task_id`，不是转换内容本身；实际内容在 `download_url` 指向的文件里。 - `state` 是字符串枚举，取值为 `preparing / processing / success / failed`，**没有数字版本**。 - `task_id` 在上传成功时生成，是整个异步链路的唯一标识，后续查询和下载都依赖它。 - `download_url` 和 `file_url` 实效 **7 天**，过期后需重新转换或查历史记录。 --- ## 为什么这个接口要设计成异步 同步返回转换内容是直觉做法，但 PDF 解析（尤其含表格、公式、图片的文档）耗时从几秒到几十秒不等，同步等待会拖垮调用方。异步模式让调用方拿到 `task_id` 后立即释放连接，再按需轮询结果，是处理耗时任务的常见范式。 代价是调用方代码多了几步：上传 → 轮询 → 下载。本文把每个字段的作用和状态流转讲清楚，避免你走弯路。 --- ## 接入点 1 返回字段（文件上传） 调用 `POST /3275-1` 后，业务数据在 `showapi_res_body` 内： | 字段 | 类型 | 说明 | |------|------|------| | `ret_code` | String | `"0"` 成功，`"-1"` 失败（注意是字符串，不是数字） | | `remark` | String | 描述信息，失败时包含原因 | | `state` | String | 处理状态：`preparing` / `processing` / `success` / `failed` | | `task_id` | String | 任务唯一 ID，**必须保存**，用于后续轮询 | | `file_name` | String | 原始文件名（UUID 格式，与上传无关） | **关键事实**：上传成功后 `state` 通常为 `preparing`（极少数情况直接为 `processing`），**不会是 `success`**。如果返回 `success`，说明该文件转换极快已完成，可直接拿 `download_url`（此时 `3275-2` 也可立即查到）。 --- ## 接入点 2 返回字段（结果查询） 调用 `POST /3275-2?task_id=xxx` 后： | 字段 | 类型 | 说明 | |------|------|------| | `ret_code` | Number | `0` 成功，`-1` 失败（此处为数字，与接入点 1 不同，以文档为准） | | `remark` | String | 描述信息，成功时为"成功" | | `state` | String | 同上，四状态枚举 | | `download_url` | String | 完整下载地址（.md 或 .docx），**实效 7 天** | | `file_url` | String | 文件地址（同 download_url，部分情况下可作快捷访问），**实效 7 天** | --- ## 状态机全貌 ``` preparing ──→ processing ──→ success ↓ failed ``` | 状态 | 含义 | 下一步动作 | |------|------|-----------| | `preparing` | 任务已进入队列，尚未开始解析 | 继续轮询，通常数秒内变为 processing | | `processing` | 正在执行 PDF 解析 | 继续轮询，耗时取决于文件页数和复杂度 | | `success` | 转换完成 | 从 `download_url` 下载结果文件 | | `failed` | 转换失败 | 查看 `remark`，排查原因后重新提交 | **实测观察**：普通 10 页以内的 PDF，从 preparing 到 success 通常在 5~15 秒内完成；含大量表格或图片的复杂文档可能需要 30 秒以上。 --- ## 常见错误排查 ### state=failed 时的排查路径 1. 先看 `remark` 字段，通常是明确的原因描述。 2. 确认 PDF 文件大小不超过 100MB。 3. 确认 PDF 不是扫描件（纯图片 PDF，无文字层），这类文件解析效果差，接口可能直接拒绝。 4. 检查 `file_url` 是否可公开访问（无鉴权、无 403）。 5. AppKey 余额不足也会导致失败，登录控制台查看资源包用量。 ### ret_code 为 -1（数字版，接入点 2 场景） `3275-2` 的 `ret_code` 是 Number 类型（与 `3275-1` 的 String 不同），传了不存在的 `task_id` 时会返回 `-1`。这种情况通常是轮询时 task_id 写错了，或该任务已超时清理。 --- ## 为什么 download_url 只有 7 天 这是 ShowAPI 的存储策略：转换结果暂存在 OSS 上 7 天，过期后自动清理，避免资源浪费。对调用方来说，这是一个明确的时效约束——**不能在代码里把 download_url 当成永久链接保存**。 正确做法：转换完成后立即下载文件并存储到自己的服务器或对象存储，后续业务直接使用本地副本。 --- ## FAQ **Q1：ret_code 为什么有的接口是 String 有的是 Number？** 接入点 1（`3275-1`）定义为 String（`"0"` / `"-1"`），接入点 2/3（`3275-2` / `3275-3`）定义为 Number（`0` / `-1`）。这是文档本身的差异，代码里做判断时用 `!= "0"` 和 `!= 0` 均可兼容（JS 弱类型），Python 建议统一转字符串比较。 **Q2：task_id 可以在不同 AppKey 之间通用吗？** 不可以。task_id 绑定到创建它的 AppKey，用另一个 AppKey 查询会返回 ret_code=-1。 **Q3：state=success 但 download_url 打不开怎么办？** 先确认是否在 7 天窗口内；若仍在窗口内，可能是转换出的文件本身有问题（如原 PDF 加密或损坏），这种情况较少见，可联系客服提供 task_id 排查。 **Q4：轮询间隔设多少合适？** 2 秒一次是合理选择，太密（1 秒）可能被限流，太稀（10 秒）体验差。实际等待时间通常不超过 15 秒，2 秒间隔足够。 --- ## 下一步阅读 - [PDF文档转换：5分钟完成异步上传与结果下载](https://www.showapi.com/guides/pdf-doc-convert-quickstart-3275) - [在知识库系统里集成PDF文档转换](https://www.showapi.com/guides/pdf-doc-convert-knowledge-base-3275) - [PDF文档转换失败怎么处理：超时、重试与7天时效下载链接管理](https://www.showapi.com/guides/pdf-doc-convert-fail-retry-3275) --- *本系列共 5 篇：查看[PDF文档转换指南总目录](https://www.showapi.com/guides/pdf-doc-convert-guides-3275)*