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 分間有効で、1 回のみ使用可能です。
2. 必要に応じてドライランを行う。 "dry_run": true を指定して開始リクエストを送信し、開始可能か、承認が必要か、ブロックされるかを確認します。何も書き込まれません。
3. 開始する。 quote_id と Idempotency-Key ヘッダーを指定して POST /videos を呼び出します。回答は 202 で、ジョブが含まれます。
4. 追跡する。 ジョブの status が変更されるまで GET /jobs/{job}/wait を呼び出すか、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）を送信してください。ネットワークが切断されて同じキーとボディで再試行した場合、2 つ目の動画が作成されるのではなく、最初の回答が返されます。キーは 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（秒）が含まれます。その時間が経過してから再試行してください。読み取り、見積もり、ステータス確認にはクレジットは消費されません。

関連情報#