# 快速开始

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

在几分钟内提交一个 PDF 转换任务并获取结果。


本指南使用 cURL 和 PDF 转 Markdown 接口。PDF 转 EPUB 也使用相同的“提交后轮询”模式。

## 1. 创建 API Key

在 [OOMOL Console](https://console.oomol.com/api-key) 创建 API Key。请将它保存在服务端或密钥管理服务中，绝不要打包到浏览器代码或公开客户端应用中。

## 2. 提交转换任务

替换示例中的 Key 与 PDF URL，然后请求提交接口。

```bash
curl --request POST "https://fusion-api.oomol.com/v1/pdf-transform-markdown/submit" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "pdfURL": "https://pdfcraft.ai/examples/api-quickstart.pdf",
    "model": "gundam"
  }'
```

响应中的 `sessionID` 就是任务 ID。建议将其与自己系统中的任务记录一同保存，并在下方替换 `TASK_ID`，以便追踪重试与下载。

## 3. 轮询结果

持续请求结果接口，直到状态为 `completed` 或 `failed`，或者达到最大尝试次数或截止时间。将所有非 2xx 响应视为错误；如果 `state` 未知，也应停止轮询。对耗时较长的文档，应先使用较短间隔，再逐步增加轮询间隔。

```bash
curl --request GET "https://fusion-api.oomol.com/v1/pdf-transform-markdown/result/TASK_ID" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

通过 `state` 判断任务状态。状态为 `completed` 时，从 `data.downloadURL` 下载生成文件；状态为 `failed` 时，记录并处理返回的失败原因。

## 下一步

- 阅读 [API 核心概念](https://pdfcraft.ai/zh-CN/docs/api/overview/)，了解认证、任务状态和重试策略。
- 需要请求和响应字段时，查阅完整 [API Reference](https://pdfcraft.ai/zh-CN/api/)。

## 首次调用的公开输入文件

可以使用这份[单页示例 PDF](https://pdfcraft.ai/examples/api-quickstart.pdf)。这是用于集成流程检查的输入样本。下载结果后，检查是否保留 `Paper to structured text.` 这句话。这是输入样本，不是 OCR 基准测试或已完成的转换结果。请求使用你自己的凭据，可能消耗额度，费用以[价格页](https://pdfcraft.ai/zh-CN/pricing/)为准。

凭据配置、错误恢复及独立的 OOMOL Connector MCP 入口见[英文 Agent 接入说明](https://pdfcraft.ai/auth.md)。

## 运行完整示例

下载并检查 [Python 3 示例](https://pdfcraft.ai/examples/api-quickstart.py)。它从环境变量读取 `PDF_CRAFT_API_KEY`，提交一次可能消耗额度的转换，保存任务 ID，在截止时间内轮询并验证下载结果。中断后继续查询同一任务，不要重复提交。

```bash
python3 api-quickstart.py
python3 api-quickstart.py --resume pdf-craft-task.json
```