Menggunakan REST API Clevera

REST API Clevera memungkinkan skrip dan layanan kamu melakukan apa yang dapat dilakukan agen melalui MCP: membaca pustaka kamu, meminta video dan artikel, mengekspor video, mengerjakan situs dokumentasi, dan mengikuti pekerjaan. Artikel ini membahas base URL, autentikasi, alur permintaan untuk pekerjaan berbayar, kesalahan, dan batas kecepatan.

Dasar-dasar#

Periksa token dengan GET /docs/me:

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

Jawaban tersebut menyatakan siapa yang ditindaklanjuti oleh token: nama dan masa berlaku token, orang tersebut dan perannya saat ini, ruang kerja, situs dalam cakupan, dan izin yang berfungsi saat ini (izin token yang disesuaikan dengan peran orang tersebut saat ini). Panggil ini terlebih dahulu saat panggilan ditolak.

Endpoint#

Setiap endpoint memerlukan izin yang ditampilkan. Memanggil salah satu tanpa izin tersebut akan mengembalikan 403 forbidden_ability. Lihat Izin agen.

Pustaka dan materi#

Video dan artikel#

Pekerjaan dan kredit#

Situs dokumentasi#

Selengkapnya tentang agen dan situs dokumentasi: Hubungkan agen AI ke situs dokumentasi kamu.

Meminta pekerjaan berbayar#

Pekerjaan yang memerlukan kredit selalu melalui penawaran terlebih dahulu, kemudian mulai:

1. Tawarkan. POST /videos/quotes (atau /clips/quotes) dengan apa yang kamu inginkan. Jawaban tersebut memiliki quote_id dan rentang kredit. Penawaran berlaku selama 15 menit dan dapat digunakan sekali.
2. Secara opsional lakukan uji coba. Kirim mulai dengan "dry_run": true untuk mengetahui apakah pekerjaan tersebut akan dimulai, memerlukan persetujuan, atau diblokir. Tidak ada yang ditulis.
3. Mulai. POST /videos dengan quote_id dan header Idempotency-Key. Jawabannya adalah 202 dengan sebuah pekerjaan.
4. Ikuti. GET /jobs/{job}/wait sampai status pekerjaan berubah, atau dengarkan 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>"}'

Status pekerjaan:

Apakah suatu pekerjaan dimulai secara langsung atau menunggu seseorang bergantung pada batas pengeluaran token dan pengaturan Setujui secara otomatis di bawah miliknya. Lihat Kontrol pengeluaran dan persetujuan agen.

Percobaan ulang dan idempotensi#

Kirim header Idempotency-Key (UUID baru per tindakan) pada setiap pembuatan dan mulai. Jika jaringan terputus dan kamu mencoba lagi dengan kunci dan body yang sama, kamu akan mendapatkan jawaban pertama kembali alih-alih video kedua. Kunci diingat selama 24 jam.

Kesalahan#

Setiap kesalahan memiliki bentuk yang sama, dengan pesan yang menyatakan apa yang harus dilakukan selanjutnya:

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

Sertakan request_id saat kamu menghubungi dukungan.

Setiap pesan, dengan perbaikannya: Perbaiki kesalahan agen dan API.

Batas kecepatan#

Jawaban 429 memiliki header Retry-After dan retry_after (detik) di dalam body. Tunggu selama itu sebelum mencoba lagi. Pembacaan, penawaran, dan pemeriksaan status tidak memakan kredit.

Terkait#