Cerul
ログイン

クイックスタート

手動でコピー

コピーが許可されていません。下の選択済みテキストをコピーしてください。

Console で作成した Key に YOUR_API_KEY を置き換え、動画一覧を取得します。接続確認のためのアップロードは不要です。

リクエスト
curl --fail-with-body "https://api.cerul.ai/videos?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

動画一覧は data に新しい順で入ります。新しい Workspace では空の一覧が正常です。ready の動画があれば検索、なければアップロードへ進みます。

リクエストパラメータ

パラメータ型 · 必須説明
Authorizationstring · 必須Bearer YOUR_API_KEY
limitinteger · 任意≥ 1; ≤ 500; default: 100
cursorstring · 任意minLength: 1; maxLength: 512
qstring · 任意minLength: 1; maxLength: 200
statusstring · 任意pattern: ^(uploading／uploaded／processing／ready／failed)(,(uploading／uploaded／processing／ready／failed))*$

必要なスコープ: videos:read.

レスポンスの読み方

data[].id は動画 ID、filename はファイル名、status は処理状況です。ready は検索可能、playable は Web 再生用コピーの準備完了を表し、先に true になることがあります。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 を保持します。

ベース 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 があれば従い、同時実行上限も確認してください。