快速開始
將 YOUR_API_KEY 換成在 Console 建立的 Key，直接執行以下請求即可列出影片，無需先上傳檔案。
curl --fail-with-body "https://api.cerul.ai/videos" \
-H "Authorization: Bearer YOUR_API_KEY"
影片清單位於 data；新工作區回傳空清單是正常結果。已有 ready 影片可直接搜尋，否則先上傳影片。
請求參數
| 參數 | 類型 · 必填 | 說明 |
|---|---|---|
| Authorization | string · 必填 | Bearer YOUR_API_KEY |
| library_id | string · 選填 | pattern: ^lib_[A-Za-z0-9_-]+$ |
閱讀回傳結果
data[].id 是影片 ID；filename 是檔名；status 表示處理狀態。ready 表示可搜尋，但仍需檢查 coverage 和 warnings，確認語音、畫面和 OCR 的實際結果。
完整範例
請在同一個 Bash 工作階段執行，需要 curl（7.76+）、jq、Python 3 與 ffprobe。影片放在 talk.mp4。處理與搜尋會消耗額度；重試相同請求時保留本次 run ID。
基礎位址為 https://api.cerul.ai，不含 /v1；標頭使用 Authorization: Bearer <API_KEY>。上傳、索引、搜尋或匯出前先驗證帳號信箱。Key 僅放伺服器端；同一 Workspace 的 Key、網頁與 CLI 雲端呼叫共用錢包。
重試與錯誤
依介面要求傳送 8–200 字元的 Idempotency-Key，搜尋也需要。回應不確定時保留原鍵與原輸入；不同操作或輸入使用新鍵。輪詢未完成工作時遵循 Retry-After 並設定期限。用戶端逾時不會取消伺服器工作。
- 401 · invalid_credentials: 確認憑證是否錯誤、過期或已撤銷。
- 403 · permission_denied / insufficient_entitlement: 檢查權限、信箱驗證、權益與錢包餘額。
- 429 · rate_limited: 若回傳 retry_after_seconds，依其退避；檢查並行限制。