Quickstart
Replace YOUR_API_KEY with a Key created in Console, then run this request to list your videos. No upload is needed to verify access.
curl --fail-with-body "https://api.cerul.ai/videos?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
The response stores videos in data, newest first. An empty list is normal in a new workspace. With a ready video, continue to Search; otherwise upload a video.
Request parameters
| Field | Type · Required | Description |
|---|---|---|
| Authorization | string · Required | Bearer YOUR_API_KEY |
| limit | integer · Optional | ≥ 1; ≤ 500; default: 100 |
| cursor | string · Optional | minLength: 1; maxLength: 512 |
| q | string · Optional | minLength: 1; maxLength: 200 |
| status | string · Optional | pattern: ^(uploading／uploaded／processing／ready／failed)(,(uploading／uploaded／processing／ready／failed))*$ |
Required scopes: videos:read.
Reading the response
data[].id identifies the video. filename is its original name; status reports processing progress. ready means searchable; playable means the web-playable copy is ready, which can happen first. indexing reports speech, screen_text and visual separately (status indexed, absent or failed, with count and reason), so a ready video may still lack one type.
Lists return at most limit videos (default 100, maximum 500). While next_cursor is not null, pass it back as cursor to read the next page. q finds a video by filename or exact ID; status filters by comma-separated states.
Complete example
Run the snippets in the same Bash session with curl (7.76+), jq, Python 3 and ffprobe installed. Set talk.mp4 to your video. Processing and search consume credits; preserve the run ID when retrying unchanged requests.
Use https://api.cerul.ai without a /v1 prefix and send Authorization: Bearer <API_KEY>. Verify your account email before uploading, indexing, searching or exporting. Keys stay on your server; a Workspace shares one cloud wallet across Keys and authenticated app/CLI calls.
Retries and errors
Send an Idempotency-Key of 8–200 characters where required, including search. Keep the same key and input after an ambiguous response; use a new key for a different operation/input. Poll pending jobs according to Retry-After and set a deadline. A client timeout does not cancel a server job.
- 401 · invalid_credentials: Check or replace the expired/revoked credential.
- 403 · permission_denied / insufficient_entitlement: Check scopes, verified email, entitlements and wallet balance.
- 429 · rate_limited: Back off using retry_after_seconds when present; check concurrency.