使用 Clevera REST API

Clevera 的 REST API 讓您的指令碼與服務能執行代理人透過 MCP 所能做的事：讀取您的媒體庫、請求影片與文章、匯出影片、處理文件網站以及追蹤工作狀態。本文涵蓋基礎 URL、驗證、付費工作的請求流程、錯誤與速率限制。

基礎知識#

使用 GET /docs/me 檢查 Token：

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

回應會說明該 Token 的身分：Token 名稱與過期時間、使用者及其目前角色、工作區、範圍內的網站，以及目前有效的權限（Token 權限會縮減為該使用者的目前角色權限）。當呼叫被拒絕時，請先呼叫此端點。

端點#

每個端點都需要顯示的權限。若在沒有權限的情況下呼叫，將會回傳 403 forbidden_ability。請參閱 代理人權限。

媒體庫與素材#

影片與文章#

工作與點數#

文件網站#

關於代理人與文件網站的更多資訊：將 AI 代理人連接到您的文件網站。

請求付費工作#

需要消耗點數的工作一律採取「先報價，後啟動」流程：

1. 報價。 POST /videos/quotes（或 /clips/quotes）並說明您的需求。回應會包含 quote_id 與點數範圍。報價有效期為 15 分鐘，且僅能使用一次。
2. 選擇性執行乾跑 (Dry-run)。 傳送啟動請求並附帶 "dry_run": true，以了解該工作是否會啟動、需要核准或被封鎖。此過程不會寫入任何資料。
3. 啟動。 POST /videos 並附帶 quote_id 與 Idempotency-Key 標頭。回應為 202 並包含工作 ID。
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>"}'

工作狀態：

啟動後是立即執行還是等待人員處理，取決於 Token 的消費上限及其 自動核准下方內容 設定。請參閱 控制代理人消費與核准。

重試與冪等性#

在每次建立與啟動請求時，請傳送 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（秒）。請等待該時間後再重試。讀取、報價與狀態檢查不消耗點數。

相關內容#