Cerul
登录

快速开始

手动复制

浏览器未允许自动复制，请复制下方已选中的内容。

把 YOUR_API_KEY 换成在 Console 创建的 Key，复制下面的请求即可列出工作区中的视频。无需先上传文件。

请求
curl --fail-with-body "https://api.cerul.ai/videos" \
  -H "Authorization: Bearer YOUR_API_KEY"

请求成功后，视频列表位于 data。新工作区没有视频时，返回空列表是正常结果。已有 ready 状态的视频，可以直接开始 搜索；还没有视频，先 上传视频。

请求参数

参数类型 · 必填说明
Authorizationstring · 必填请求头。格式为 Bearer 加上你的 API Key。需要 assets:read 权限。
library_idstring · 可选URL 查询参数。只列出指定资料库中的视频；省略时列出工作区中的视频。 — pattern: ^lib_[A-Za-z0-9_-]+$

按资料库筛选时，在 URL 后添加 ?library_id=YOUR_LIBRARY_ID。基础地址统一为 https://api.cerul.ai，不加 /v1。

返回结果怎么看

参数必填说明
data[].id返回字段视频 ID。后续查询、搜索和剪辑都用它关联视频。
data[].filename返回字段上传时的文件名。
data[].status返回字段ready 表示可搜索；processing 表示仍在处理。
data[].coverage返回字段语音、画面和 OCR 的实际处理情况；就绪不保证每种证据都完整。

接下来做什么

  1. 上传视频：上传文件，等待索引就绪。
  2. 搜索：发送自然语言查询，取得证据和时间范围。
  3. 导出剪辑：把选中的片段保存为视频文件。

需要一次跑通整个流程？下载完整示例脚本，准备 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 便于排查。客户端超时不会自动取消服务端处理。