Sử dụng Clevera REST API

REST API của Clevera cho phép các tập lệnh và dịch vụ của riêng bạn thực hiện những gì một tác nhân có thể làm qua MCP: đọc thư viện, yêu cầu video và bài viết, xuất video, làm việc trên các trang tài liệu và theo dõi các công việc. Bài viết này bao gồm URL cơ sở, xác thực, quy trình yêu cầu cho công việc trả phí, các lỗi và giới hạn tốc độ.

Thông tin cơ bản#

Kiểm tra một token với GET /docs/me:

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

Câu trả lời cho biết token đó đại diện cho ai: tên và thời hạn của token, người dùng và vai trò hiện tại của họ, không gian làm việc, các trang web trong phạm vi và các quyền hiện đang hoạt động (quyền của token được cắt giảm theo vai trò hiện tại của người dùng). Hãy gọi lệnh này trước tiên khi một yêu cầu bị từ chối.

Các điểm cuối (Endpoints)#

Mỗi điểm cuối cần quyền hạn được hiển thị. Việc gọi một điểm cuối mà không có quyền đó sẽ trả về 403 forbidden_ability. Xem Quyền của tác nhân.

Thư viện và tài liệu#

Video và bài viết#

Công việc và tín dụng#

Các trang tài liệu#

Xem thêm về các tác nhân và trang tài liệu: Kết nối các tác nhân AI với trang tài liệu của bạn.

Yêu cầu công việc trả phí#

Công việc tốn tín dụng luôn thực hiện theo quy trình báo giá trước, sau đó mới bắt đầu:

1. Báo giá. POST /videos/quotes (hoặc /clips/quotes) với những gì bạn muốn. Câu trả lời có chứa quote_id và phạm vi tín dụng. Báo giá có hiệu lực trong 15 phút và chỉ có thể sử dụng một lần.
2. Tùy chọn chạy thử (dry-run). Gửi lệnh bắt đầu với "dry_run": true để biết liệu công việc có bắt đầu được không, có cần phê duyệt hay bị chặn. Không có gì được ghi lại.
3. Bắt đầu. POST /videos với quote_id và tiêu đề Idempotency-Key. Câu trả lời là 202 kèm theo một công việc.
4. Theo dõi. GET /jobs/{job}/wait cho đến khi status của công việc thay đổi, hoặc lắng nghe webhooks.

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>"}'

Các trạng thái công việc:

Việc bắt đầu chạy ngay lập tức hay chờ người dùng phụ thuộc vào giới hạn chi tiêu của token và cài đặt Tự động phê duyệt bên dưới của nó. Xem Kiểm soát chi tiêu và phê duyệt của tác nhân.

Thử lại và tính lũy đẳng#

Gửi tiêu đề Idempotency-Key (một UUID mới cho mỗi hành động) trong mỗi lần tạo và bắt đầu. Nếu mạng bị ngắt và bạn thử lại với cùng một khóa và nội dung, bạn sẽ nhận lại câu trả lời đầu tiên thay vì tạo ra video thứ hai. Các khóa được ghi nhớ trong 24 giờ.

Lỗi#

Mỗi lỗi đều có cùng một hình thức, với thông báo cho biết cần làm gì tiếp theo:

{
  "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"
}

Hãy bao gồm request_id khi bạn liên hệ với bộ phận hỗ trợ.

Mỗi thông báo, cùng với cách khắc phục: Khắc phục lỗi tác nhân và API.

Giới hạn tốc độ#

Câu trả lời 429 có chứa tiêu đề Retry-After và retry_after (giây) trong phần thân. Hãy chờ khoảng thời gian đó trước khi thử lại. Các thao tác đọc, báo giá và kiểm tra trạng thái không tốn tín dụng.

Liên quan#