# API 概念

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

了解驗證、非同步任務，以及文件轉換 API 的生命週期。


PDF Craft API 採用 REST 架構，使用 JSON 請求與回應，並透過 Bearer API 金鑰驗證每次請求。

## 基礎 URL 與驗證

所有端點皆位於 `https://fusion-api.oomol.com/v1` 之下。請透過 `Authorization` 請求標頭傳送 API 金鑰。

```text
Authorization: Bearer YOUR_API_KEY
```

請勿在前端程式碼中暴露此金鑰。當使用者啟動轉換時，請透過你自己的後端處理瀏覽器發起的請求。

## 非同步任務生命週期

文件轉換採非同步方式執行。提交端點會回傳任務識別碼 `sessionID`，對應的結果端點則會回報以下狀態之一：

- `processing`：檔案正在等待或轉換中。
- `completed`：結果包含 `data.downloadURL` 中的輸出檔案 URL 及其中繼資料。
- `failed`：結果包含失敗原因，你的應用程式應顯示或記錄該原因。

整合程式應在任務進入最終狀態時停止輪詢，限制重試次數，並保留任務 ID 以便支援與復原。

## 端點

目前 API 支援將 PDF 轉換為 Markdown 和 EPUB。請參閱完整的 [API 參考文件](https://pdfcraft.ai/zh-Hant/api/)，了解端點路徑、參數、請求範例、Python SDK 指南與 TypeScript SDK 指南。