快速開始
將 YOUR_API_KEY 換成在 Console 建立的 Key，直接執行以下請求即可列出影片，無需先上傳檔案。
curl --fail-with-body "https://api.cerul.ai/videos?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
影片清單位於 data，依建立時間由新到舊排列；新工作區回傳空清單是正常結果。已有 ready 影片可直接搜尋，否則先上傳影片。
請求參數
| 參數 | 類型 · 必填 | 說明 |
|---|---|---|
| Authorization | string · 必填 | Bearer YOUR_API_KEY |
| limit | integer · 選填 | ≥ 1; ≤ 500; default: 100 |
| cursor | string · 選填 | minLength: 1; maxLength: 512 |
| q | string · 選填 | minLength: 1; maxLength: 200 |
| status | string · 選填 | pattern: ^(uploading／uploaded／processing／ready／failed)(,(uploading／uploaded／processing／ready／failed))*$ |
所需權限: videos:read.
閱讀回傳結果
data[].id 是影片 ID；filename 是檔名；status 表示處理狀態。ready 表示可搜尋；playable 表示網頁可播放副本已就緒，可能早於可搜尋。indexing 分別列出語音（speech）、螢幕文字（screen_text）與畫面（visual）的結果（status 為 indexed、absent 或 failed，並附 count 與 reason），ready 的影片仍可能缺少某一類。
每頁最多回傳 limit 部影片（預設 100，最多 500）。next_cursor 不為 null 時，將它作為 cursor 傳回即可讀取下一頁。q 依檔名或完整影片 ID 查找；status 以逗號分隔的狀態篩選。
完整範例
請在同一個 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，依其退避；檢查並行限制。