# API 核心概念

[HTML](https://pdfcraft.ai/zh-CN/docs/api/overview/) · [Site index](https://pdfcraft.ai/llms.txt)

了解认证、异步任务以及文档转换 API 的完整生命周期。


PDF Craft API 使用 REST 风格、JSON 请求和响应，并通过 Bearer API Key 对每次请求进行认证。

## 基础地址与认证

所有接口均位于 `https://fusion-api.oomol.com/v1` 下方。通过 `Authorization` 请求头传入 API Key。

```text
Authorization: Bearer YOUR_API_KEY
```

不要在前端代码中暴露这个 Key。若浏览器端需要由用户发起转换，请先把请求发送到你自己的后端。

## 异步任务生命周期

文档转换是异步操作。提交接口会返回任务 ID（`sessionID`），结果接口会报告以下状态之一：

- `processing`：文件正在等待或转换中。
- `completed`：结果中通过 `data.downloadURL` 包含生成文件的 URL 与元数据。
- `failed`：结果中包含失败原因，应用应向用户展示可操作的下一步或记录日志。

接入方应在终态时停止轮询，设置有限的重试策略，并保存任务 ID 以便支持排查与恢复。

## 接口范围

当前 API 支持 PDF 转 Markdown 和 PDF 转 EPUB。完整 [API Reference](https://pdfcraft.ai/zh-CN/api/) 提供接口路径、参数、示例请求、Python SDK 和 TypeScript SDK 的详细信息。