RetainPDF 开放 API 速查从创建翻译任务到事件流与产物下载的完整接入手册【免费下载链接】retain-pdf在保留版面、公式与结构的前提下进行 PDF 翻译适用于科研与技术文档项目地址: https://gitcode.com/gh_mirrors/re/retain-pdfRetainPDF 是一款保留版面、公式与结构进行 PDF 翻译的开源工具面向科研与技术文档场景。本文基于其官方 API 文档完整梳理 RetainPDF 开放 API 的接入路径鉴权与响应约定、上传 PDF 并创建翻译任务、查询任务状态与事件流、失败重试与阶段控制、下载译文 PDF / Markdown / 打包产物帮助新手一次性跑通从提交到产出的全链路。上图为 RetainPDF 典型处理对象带公式、图表的双栏科研论文翻译后版面与结构保持不变一、接入全景5 步完成一次 PDF 翻译整个接入流程只有 5 步对应 5 类端点步骤端点说明1️⃣ 上传 PDFPOST /api/v1/uploadsmultipart 上传返回upload_id2️⃣ 创建翻译任务POST /api/v1/jobs指定 workflow 与翻译/渲染参数3️⃣ 查询任务状态GET /api/v1/jobs/{job_id}stage_snapshot是唯一进度真相4️⃣ 事件流GET /api/v1/jobs/{job_id}/events历史时间线与排障5️⃣ 下载产物GET /api/v1/jobs/{job_id}/pdf等译文 PDF / Markdown / ZIP 包 端点清单维护在官方契约文档 jobs.md全局 HTTP 约定见 API_SPEC.md。二、API 约定与鉴权X-API-Key 与统一响应包1. 鉴权一个请求头就够除GET /health外所有请求都要携带后端 API keyX-API-Key: your-rust-api-key注意这个 key 是访问 RetainPDF 后端 API 的白名单 key不是 DeepSeek / MinerU / Paddle 的模型或 OCR token下游模型与 OCR 的凭证通过任务请求里的credential_ref或兼容的内联字段传入响应中永远不会回显明文密钥。本地开发时的 key 来源、默认端口完整 API41000multipart 提交端口42000见 local-dev.md本地示例配置参考 auth.local.example.json。2. 统一 JSON 响应包成功响应固定为{ code: 0, message: ok, data: { } }错误响应额外包含权威错误对象error {code, http_status, details}。新客户端应一律按error.code分支如BAD_REQUEST、NOT_FOUND、CONFLICT、PAYLOAD_TOO_LARGE错误码完整规则见 storage-and-errors.md。三、创建翻译任务上传 PDF 与 POST /api/v1/jobs1. 上传 PDF 拿 upload_idPOST /api/v1/uploads提交 multipart 字段filePDF 文件。成功后返回upload_id、文件名、字节数与页数{ code: 0, message: ok, data: { upload_id: 20260327190000-ab12cd, filename: paper.pdf, bytes: 1234567, page_count: 18 } }单文件默认上限 512 MiB超过返回413/PAYLOAD_TOO_LARGE。上传与任务创建的完整细节修复、队列、限制见 jobs-submission.md。2. 选择 workflowbook / translate / render / ocrworkflow决定跑哪条流水线OCR provider 的选择在ocr.provider字段两者不要混淆workflow含义链路book全流程正式主链路OCR → Normalize → Translate → Rendertranslate只翻译不出 PDFOCR → Normalize → Translaterender复用已有翻译产物只重新渲染RenderocrOCR-only 子流程POST /api/v1/ocr/jobsprovider → normalize当前可用的 provider 列表、所需凭证类型与能力可通过GET /api/v1/providers/ocr动态发现无需硬编码。3. 创建任务的最小请求POST /api/v1/jobs的核心字段完整字段以 create-job.v1.schema.json 为准{ workflow: book, source: { upload_id: 20260327190000-ab12cd }, ocr: { provider: paddle, credential_ref: cred_ocr_xxx }, translation: { mode: sci, model: deepseek-flash, base_url: https://api.deepseek.com/v1, credential_ref: cred_xxx, glossary_id: }, render: { render_mode: auto }, runtime: { timeout_seconds: 1800 } }常用可定制点术语表translation.glossary_id命名资源或translation.glossary_entries内联数组仅作为提示引导不做强制替换翻译模型translation.model/translation.base_urlcredential_ref渲染参数render.source_cleanup_strategy默认pikepdf_text_strip、字号与行距系数等规范见 RENDER_OPTIONS_CONTRACT.md双超时runtime.timeout_seconds限制整单总时长大书要按小时给runtime.no_output_timeout_seconds只盯着 worker 是否卡死不动4. 提交响应与 OCR 产物复用响应立即返回job_id、status: queued和三阶段状态投影并附带links/actions详情、事件、产物、取消等现成路径前端可直接消费{ job_id: 20260327190500-ef3456, status: queued, workflow: book, ocr_reused: false, stages: { ocr: { state: pending }, translation: { state: pending }, render: { state: pending } } }省钱技巧source.artifact_job_id可复用某个已成功任务的 OCR 产物跳过昂贵的 OCR 阶段直接翻译/渲染。复用校验失败不会静默回退到重新 OCR而是返回409如OCR_ARTIFACT_NOT_REUSABLE、OCR_PAGE_COVERAGE_MISMATCH并附can_fallback_to_ocrtrue需要你显式去掉artifact_job_id重新提交。四、查询任务状态与事件流轮询与时间线1. 状态模型5 个状态 stage_snapshot任务状态只有 5 种queued→running→succeeded/failed/canceled。队列语义新建任务进入queued最多RUST_API_MAX_RUNNING_JOBS个任务并行槽位释放后自动开始。关键规则任务详情/列表里的stage_snapshot是当前阶段与进度的唯一权威来源不要用历史事件反推当前阶段。列表与详情的稳定字段含stage_snapshot、stages、output_pdf_ready、markdown_ready、bundle_ready等见 jobs-query.md。2. 事件流接口GET /api/v1/jobs/{job_id}/events查询参数limit默认 100上限 500与offset按seq升序返回。主任务事件流会自动合并 OCR 子任务{job_id}-ocr的事件并映射回主任务你不需要单独轮询子任务。每条事件都带齐展示所需字段{ job_id: 20260514-xxxx, seq: 42, display_stage: ocr, stage: ocr_processing, substage: provider_processing, stage_detail: Paddle 正在解析文件第 12/34 页, event_type: progress, progress: { unit: page, current: 12, total: 34 } }各阶段的进度单位是约定好的OCR 用page翻译批次用batch渲染页用page无法按页汇报的 Typst 编译等步骤用step。事件字段与前端展示口径的完整约定见 02-display-stage与lane.md。3. 任务失败怎么看失败任务是结构化分类的详情里data.failure含failed_stage、failure_code、failure_category、retryable、suggestion、last_log_line等字段另有GET /api/v1/jobs/{job_id}/diagnostics提供排障投影含render_diagnostics。失败结构详见 01-失败结构.md。五、失败重试与阶段控制retry-stage / cancel / rerun失败后不必从头再来。RetainPDF 提供阶段级重试契约先问后端GET /api/v1/jobs/{job_id}/stage-actions返回每个阶段ocr / translation / render是否可重试以及会复用哪些产物、重跑哪些阶段——例如重试翻译会复用source_pdf ocr_result只重跑 translation 和 render再发起POST /api/v1/jobs/{job_id}/retry-stage请求体携带stage可在overrides里换模型、术语表、并发数等参数{ stage: translation, ambiguous_request_policy: block, overrides: { translation: { model: deepseek-flash, workers: 50 } } }其他控制端点POST /api/v1/jobs/{job_id}/cancel取消任务POST /api/v1/jobs/{job_id}/rerun复用同一job_id重新渲染GET /api/v1/jobs/{job_id}/resume-planPOST .../resume失败恢复计划注意排队/运行中的任务会返回禁用的 stage action需先 cancel 再重试状态冲突返回409而不是覆盖新状态。完整规则见 jobs-retry-and-control.md。六、产物下载译文 PDF、Markdown 与打包 ZIP任务成功后GET /api/v1/jobs/{job_id}/artifacts会返回一份结构化 URL 清单不泄露本地路径前端只需要消费 URL端点产物说明GET /api/v1/jobs/{job_id}/pdf译文 PDFapplication/pdf原始流GET /api/v1/jobs/{job_id}/pdf/side-by-side对照 PDF左原文右译文并排GET /api/v1/jobs/{job_id}/markdown?rawtrue译文 Markdown支持 HTTPRange分段读取长文档GET /api/v1/jobs/{job_id}/markdown/images/{path}Markdown 配图原始图片流GET /api/v1/jobs/{job_id}/cover/.../thumbnail封面 / 缩略图原始图片GET /api/v1/jobs/{job_id}/download打包 ZIP译文 PDF markdown/full.md 全部图片GET /api/v1/jobs/{job_id}/normalized-document归一化文档document.v1.json程序化二次处理用 一次download就能拿走全部成果适合批量集成场景分端点下载则适合做进度 UI每个产物都有ready布尔值与size_bytes。端点细节与 Markdown 分段读取技巧见 artifacts.md下载总览见 01-下载总览.md。七、延伸阅读官方文档与源码入口主题文档后端 API 总入口前端/第三方集成index.md任务提交契约上传 / 创建 / OCR 复用jobs-submission.md任务查询与列表投影jobs-query.md事件流与运行时约定runtime-and-events.md当前 API 运行主链CURRENT_API_MAP.md本地启动与鉴权local-dev.md创建任务字段 TypeScript 契约create-job.ts任务路由实现src/routes/jobs/结语RetainPDF API 的设计非常契约化X-API-Key一个请求头搞定鉴权workflow ocr.provider分开选择流程与引擎stage_snapshot一个字段看懂进度stage-actions一个端点告诉你能重试什么。按照「上传 → 创建 → 轮询 → 重试 → 下载」五步走你就可以把科研 PDF 批量翻译流水线接进自己的系统。【免费下载链接】retain-pdf在保留版面、公式与结构的前提下进行 PDF 翻译适用于科研与技术文档项目地址: https://gitcode.com/gh_mirrors/re/retain-pdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考