面向開發者

HTTP API

本網站本身就是一套純 HTTP API 的用戶端 —— 拖放區能做的一切，你都可以用 curl 完成。API Beta 期間免費、無需 API Key。限流：每 IP 每分鐘 30 次寫入請求，另有每日免費額度（20 次轉換 / 3 次語音 / 30 次探測 —— 失敗自動返還）。AI 代理人：把 /skill.md 給它 —— 本頁全部內容都有面向代理人的版本。

驗證與每日額度

API 無需 API Key 即可使用：匿名呼叫共享每 IP 免費額度（L1）。需要更高額度的 Agent 與腳本可以使用 API Key（L2b）—— 到帳號頁簽發，以 Bearer 方式攜帶，每把 Key 有獨立的每日額度。Key 僅以 SHA-256 雜湊儲存，明文只在簽發時顯示一次，也不會出現在任何日誌中。

身分	轉換/天	語音/天	檔案探測/天
匿名（按 IP）—— L1	20	3	30
API Key（每把 Key）—— L2b	500	20	300

每日額度在 UTC 午夜重置；失敗的轉換自動返還。寫入請求限流為每 IP 每分鐘 30 次。

# 匿名（L1）—— 無需 API Key
curl -X POST https://liteconvert.cc/api/public/detect -F "file=@document.pdf"

# 攜帶 API Key（L2b）—— 用你簽發的 Key 取代範例中的佔位 API Key
curl -X POST https://liteconvert.cc/api/public/convert \
  -H "Authorization: Bearer sk-…" \
  -F 'meta={"conversion":"pdf-docx"};type=application/json' \
  -F "file=@document.pdf"

401 INVALID_API_KEY：以 Bearer 形式出示的 Key 校驗失敗（無效或已撤銷）—— 已出示的 Key 一律拒絕，絕不降級為匿名；未攜帶 Key，或 Authorization 標頭不是 Bearer 形式的請求，計入匿名 L1 額度。429 QUOTA_EXCEEDED：目前身分當日額度已用完；error.reset_at 給出準確重置時間（UTC 午夜）。

需要更高額度 —— 到帳號頁簽發 API Key。

端點

方法	路徑	作用
POST	/api/public/detect	識別檔案（multipart file 欄位）。同步，≤20 秒。
POST	/api/public/convert	提交轉換（multipart meta + 檔案）。回傳 request_id。
GET	/api/public/requests/{id}	請求的狀態、進度與產物。
GET	/api/public/requests/recent?limit=20	本裝置的最近轉換（X-Owner-Token 標頭，匿名）。
GET	/api/public/requests/{id}/artifacts/{name}	302 重新導向到預簽名下載網址。
GET	/api/public/requests/{id}/timeline	人類可讀的轉換事件軌跡。
GET	/api/public/stats	即時成功率統計。
GET	/api/public/conversions	轉換目錄（全部支援的轉換對）。
GET	/api/public/catalog	面向網站建置方的建置清單（canonical 鍵，含 family/lossy/steps）。

探測檔案

curl -X POST https://liteconvert.cc/api/public/detect -F "file=@document.pdf"

{
  "request_id": "c0af…",
  "status": "succeeded",
  "report": { "declared": "pdf", "detected": "pdf", "match": true,
              "mime": "application/pdf", "confidence": 0.99 }
}

轉換並下載

# 1. 提交（URL 來源傳送帶 source_url 的 meta，無檔案部分）
curl -X POST https://liteconvert.cc/api/public/convert \
  -F 'meta={"conversion":"pdf-docx"};type=application/json' \
  -F "file=@document.pdf"
# → 202 { "request_id": "…", "status": "running" }

# 2. 輪詢
curl https://liteconvert.cc/api/public/requests/REQUEST_ID
# → { "status": "succeeded", "artifacts": [{ "name": "docx", "download": "…", … }] }

# 3. 下載（302 到預簽名網址，1 小時有效）
curl -L -o result.docx https://liteconvert.cc/api/public/requests/REQUEST_ID/artifacts/docx

錯誤碼

狀態	錯誤碼	含義
401	INVALID_API_KEY	出示的 Key 無效，或該 Key 已被撤銷。撤銷立即生效 —— 請到帳號頁簽發新 Key。
429	QUOTA_EXCEEDED	當日免費額度已用完（UTC 午夜重置；error.reset_at 帶準確時間）。失敗的轉換會自動返還額度。
422	UNSUPPORTED_CONVERSION	轉換對不在目錄中。
404	ARTIFACT_EXPIRED	結果已過期並被刪除（保留 24 小時）—— 請重新轉換。
413/422	INTAKE_FAILED	上傳失敗或超過 200 MB。
502	CONVERT_FAILED	引擎已嘗試但無法讀取該檔案。細分碼（NEEDS_OCR、ENCRYPTED_DOCUMENT、MALFORMED_DOCUMENT）透過請求詳情的 error.code 回傳，訊息為固定文案。
400	INVALID_SOURCE_URL	source_url 缺失，或不是合法的公開 http(s) 網址。
400	SOURCE_URL_BLOCKED	來源位址解析到私有、回環或鏈路本機位址，已被封鎖（SSRF 防護）。
502	SOURCE_URL_FETCH_FAILED	來源位址無法下載 —— 離線、逾時、過大或無法公開存取。
503	CONVERT_API_UNAVAILABLE	臨時故障 —— 請一分鐘後再試。

面向 AI 代理人

擷取 /skill.md —— 它是一份自包含的說明，包含上述端點、完整範例與免費方案聲明。不確定時先重讀它；它會隨 API 一起更新。