使用 Clevera REST API

Clevera 的 REST API 让你的脚本和服务能够执行智能体通过 MCP 所能完成的操作：读取你的库、请求视频和文章、导出视频、处理文档站点以及跟踪任务。本文涵盖了基础 URL、身份验证、付费工作的请求流程、错误以及速率限制。

基础知识#

使用 GET /docs/me 检查令牌：

curl -H "Authorization: Bearer $CLEVERA_TOKEN" \
     -H "Accept: application/json" \
     https://app.clevera.ai/api/v1/docs/me

响应会说明该令牌代表谁执行操作：令牌的名称和有效期、人员及其当前角色、工作区、作用域内的站点以及当前生效的权限（令牌权限会根据人员的当前角色进行裁剪）。当调用被拒绝时，请首先调用此接口。

端点#

每个端点都需要所示的权限。在没有权限的情况下调用会返回 403 forbidden_ability。请参阅 智能体权限。

库与素材#

视频与文章#

任务与额度#

文档站点#

关于智能体和文档站点的更多信息：将 AI 智能体连接到你的文档站点。

请求付费工作#

消耗额度的工作总是遵循先报价，后启动的流程：

1. 报价。 使用 POST /videos/quotes（或 /clips/quotes）提交你的需求。响应包含 quote_id 和额度范围。报价有效期为 15 分钟，且仅可使用一次。
2. 可选的试运行。 发送带有 "dry_run": true 的启动请求，以了解它是否会启动、是否需要批准或被阻止。不会写入任何内容。
3. 启动。 使用 POST /videos、quote_id 和 Idempotency-Key 标头进行启动。响应为 202，包含一个任务。
4. 跟踪。 轮询 GET /jobs/{job}/wait 直到任务的 status 发生变化，或者监听 Webhook。

curl -X POST https://app.clevera.ai/api/v1/videos/quotes \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "how_to", "recording_id": "<recording id>", "language": "en-US"}'

curl -X POST https://app.clevera.ai/api/v1/videos \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1a2e-8d4b-4f7a-9c1e-2b5d7e9f0a13" \
  -d '{"quote_id": "<quote id>"}'

任务状态：

启动是立即运行还是等待人员处理，取决于令牌的支出上限及其 在下方自动批准 设置。请参阅 控制智能体支出和批准。

重试与幂等性#

在每次创建和启动时发送 Idempotency-Key 标头（每个操作一个全新的 UUID）。如果网络中断，你使用相同的键和正文重试，你将获得第一次的响应，而不是生成第二个视频。键的有效期为 24 小时。

错误#

每个错误都有相同的格式，并附带一条说明后续操作的消息：

{
  "error": {
    "code": "forbidden_ability",
    "message": "This token lacks the videos:create ability. Ask the workspace member who owns it for a token that has it.",
    "details": { "ability": "videos:create" }
  },
  "request_id": "req_example"
}

联系支持团队时，请包含 request_id。

每条消息及其修复方法：修复智能体和 API 错误。

速率限制#

429 响应包含 Retry-After 标头，正文中包含 retry_after（秒）。请等待相应时间后再重试。读取、报价和状态检查不消耗额度。

相关内容#