快速开始

把 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 加上你的 API Key。需要 videos:read 权限。
limit	integer · 可选	URL 查询参数。每页最多返回的视频数，默认 100，最大 500。 — ≥ 1; ≤ 500; default: 100
cursor	string · 可选	URL 查询参数。填入上一页返回的 next_cursor，读取下一页。 — minLength: 1; maxLength: 512
q	string · 可选	URL 查询参数。按文件名（不区分大小写的部分匹配）或完整的视频 ID 查找。 — minLength: 1; maxLength: 200
status	string · 可选	URL 查询参数。只列出这些状态的视频，多个状态用逗号分隔，例如 processing,ready。 — pattern: ^(uploading／uploaded／processing／ready／failed)(,(uploading／uploaded／processing／ready／failed))*$

基础地址统一为 https://api.cerul.ai，不加 /v1。

参数	必填	说明
data[].id	返回字段	视频 ID。后续查询、搜索和导出都用它关联视频。
data[].filename	返回字段	上传时的文件名。
data[].status	返回字段	ready 表示可搜索；processing 表示仍在处理；failed 时查看 error。
data[].playable	返回字段	网页可播放副本是否就绪。视频可能先可播放、后可搜索。
data[].indexing	返回字段	语音、屏幕文字和画面各自的索引结果（status、count、reason）；ready 不保证每种类型都已建立。
next_cursor	返回字段	还有下一页时，把它作为 cursor 传回；最后一页为 null。

需要一次跑通整个流程？下载完整示例脚本，准备 talk.mp4，设置 CERUL_API_KEY 后用 Bash 运行。需要 curl 7.76+、jq、Python 3、ffprobe 和 uuidgen；示例中的索引和搜索会消耗额度。

Key 保存在服务端或本机环境变量中，不放在网页前端。上传、索引、搜索和导出前需验证账号邮箱，并确认相应权限及可用额度。

创建、索引、搜索、导出等接口按要求携带 8–200 字符的 Idempotency-Key。同一次操作响应不确定时，使用原键和原请求内容重试；修改输入或新建操作时换一个键。

401 检查 Key；403 检查权限、邮箱验证与额度；429 按 retry_after_seconds 退避。保留 request_id 便于排查。客户端超时不会自动取消服务端处理。