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) 수행. "dry_run": true과 함께 시작 요청을 보내 작업이 시작될지, 승인이 필요한지, 차단될지 확인합니다. 아무것도 작성되지 않습니다.
3. 작업 시작. quote_id 및 Idempotency-Key 헤더와 함께 POST /videos를 호출합니다. 응답은 작업이 포함된 202입니다.
4. 작업 추적. 작업의 status가 변경될 때까지 GET /jobs/{job}/wait을 호출하거나 웹훅을 수신 대기합니다.

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(초)가 포함됩니다. 재시도하기 전에 해당 시간만큼 기다리세요. 읽기, 견적 및 상태 확인은 크레딧을 소모하지 않습니다.

관련 항목#