クイックスタート
Console で作成した Key に YOUR_API_KEY を置き換え、動画一覧を取得します。接続確認のためのアップロードは不要です。
curl --fail-with-body "https://api.cerul.ai/videos" \
-H "Authorization: Bearer YOUR_API_KEY"
動画一覧は data に入ります。新しい Workspace では空の一覧が正常です。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 を保持します。
ベース URL は https://api.cerul.ai（/v1 なし）です。Authorization: Bearer <API_KEY> を送信します。アップロード、索引化、検索、書き出しの前にメールを確認してください。Key はサーバー側で保持し、同じ Workspace の Key・Web・CLI のクラウド呼び出しは一つの残高を共有します。
再試行とエラー
検索を含め、必要な API には 8～200 文字の Idempotency-Key を送信します。結果が不明な場合は同じキーと入力で再試行し、異なる操作や入力には新しいキーを使います。待機中のジョブは Retry-After に従い、期限を設定します。クライアントのタイムアウトはジョブを取り消しません。
- 401 · invalid_credentials: 認証情報の誤り・期限切れ・失効を確認してください。
- 403 · permission_denied / insufficient_entitlement: スコープ、メール確認、利用権、残高を確認してください。
- 429 · rate_limited: retry_after_seconds があれば従い、同時実行上限も確認してください。