# 快速開始

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

提交 PDF 轉換任務並在幾分鐘內取得結果。


本指南使用 cURL 和 PDF-to-Markdown 端點。相同的提交與輪詢模式也適用於 EPUB 轉換。

## 1. 建立 API 金鑰

在 [OOMOL Console](https://console.oomol.com/api-key) 中建立 API 金鑰。請將其保存在您的伺服器或密鑰管理器中；切勿將其包含在瀏覽器套件或公開的用戶端應用程式中。

## 2. 提交轉換任務

替換範例金鑰和 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-Hant/docs/api/overview/) 以了解驗證、任務狀態和重試。
- 當您需要欄位層級的請求和回應詳細資訊時，請使用 [API Reference](https://pdfcraft.ai/zh-Hant/api/)。

## 執行完整範例

下載並檢查 [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
```