API 参考

常规研究工作流建议使用 Python CLI。本页面面向需要直接集成 Mdtero 稳定任务 API 的客户端。

Base URL 与鉴权

https://api.mdtero.com

使用在 Mdtero Account 创建的 API key：

Authorization: Bearer mdtero_...
Content-Type: application/json

不要把 API key 放进 shell history、日志或聊天。优先使用 mdtero setup 的安全登录流程。

任务生命周期

CLI、浏览器扩展、Dashboard 和直连 API 客户端使用同一公开流程：

1. 提交 DOI、URL 或有权使用的本地文件。
2. 轮询任务，直到成功或需要用户处理。
3. 下载 Markdown 或 bundle。
4. 按需翻译 Markdown 或导入项目。

任务响应会提供 task_id、status、可用时的质量提示、首选下载成果，以及失败时面向用户的下一步操作。采集与解析的实现细节不属于公开 API 契约。

解析 DOI 或 URL

POST /api/v1/tasks/parse

POST /api/v1/tasks/parse
Authorization: Bearer mdtero_...
Content-Type: application/json

{"input":"10.48550/arXiv.1706.03762"}

input 可以是 DOI、arXiv 标识符或文章 URL。响应会返回用于轮询的任务 id。

CLI 等价命令：

mdtero parse <doi-or-url> --wait --timeout 300 --json

上传文件

POST /api/v1/tasks/upload

POST /api/v1/tasks/upload
Authorization: Bearer mdtero_...
Content-Type: multipart/form-data

字段	必填	说明
paper_file	是	PDF、EPUB、HTML、XML、JATS/NXML 或 TEI 文件。
source_doi	否	与文件关联的 DOI。
source_input	否	原始 DOI 或 URL。
artifact_kind	否	pdf、epub、html 或 structured_xml。

使用上传处理已保存的文件，包括通过你自己的浏览器登录态或机构访问获得的内容。

mdtero parse --file <paper.pdf|paper.epub|paper.html|paper.xml> --wait --timeout 600 --json

查看状态与下载

GET /api/v1/tasks/{task_id}

轮询解析或翻译任务。常见状态为 queued、running、succeeded 和 failed。

GET /api/v1/tasks/{task_id}/download/{artifact}

常见成果：

成果	内容
paper_md	主要 Markdown 输出。
paper_bundle	含 Markdown 与相关资源的 ZIP bundle。
translated_md	翻译任务生成的 Markdown。

mdtero status <task-id> --wait --timeout 300 --json
mdtero download <task-id> paper_md --output-dir ./mdtero-output --json

检索与翻译

GET /api/v1/discovery/search

检索 Mdtero 的论文发现目录。

参数	说明
query	必填，检索词。
limit	结果数量。
year_from、year_to	可选年份筛选。
open_access_only	仅返回开放获取记录。

POST /api/v1/tasks/translate

翻译已完成任务中的 Markdown，或直接提交 Markdown 文本。传入 target_language，例如 zh-CN；mode 可省略，默认值为 full。随后轮询返回的任务并下载 translated_md。

mdtero translate <parse-task-id> --to zh-CN --wait --timeout 600 --json

项目与带引文问答

POST /api/v1/projects

创建项目，用于整理已处理的论文。

POST /api/v1/projects/{project_id}/tasks/{task_id}/import

将成功解析任务的 Markdown 加入项目。

GET /api/v1/projects/{project_id}/rag/status

查看项目是否已可提问。

POST /api/v1/projects/{project_id}/rag/build

导入文档后构建项目索引。

POST /api/v1/projects/{project_id}/rag/query

对项目提问：

{"question":"最重要的发现是什么？","limit":5}

输出研究结论时请保留返回的引文。CLI 可以管理完整项目流程：

mdtero rag query "最重要的发现是什么？" --build-if-needed --json

错误处理

HTTP	含义	下一步
400 / 422	输入无效或不完整。	修正请求后重试。
401	需要登录或 API key。	运行 mdtero setup 或重新登录。
403	资源属于其他账户，或来源需要你的授权。	使用正确账户，或上传你有权使用的文件。
404	找不到任务、项目或成果。	检查 id 与账户。
413	文件过大。	缩小文件后重试。
429 / 503	临时容量或上游可用性问题。	稍后重试。

本地使用优先选择 CLI：它会处理登录、轮询、下载和清晰的下一步，而不暴露实现细节。