ข้ามไปยังเนื้อหา
Clevera Help Center

ใช้งาน Clevera REST API

เรียกใช้ Clevera จากสคริปต์ของคุณเอง: URL พื้นฐาน, การยืนยันตัวตนด้วย bearer-token, เอนด์พอยต์และสิทธิ์ที่จำเป็นสำหรับแต่ละรายการ, ขั้นตอนการขอใบเสนอราคาก่อนเริ่มงานสำหรับงานที่ต้องชำระเงิน, ความเป็นเอกภาพ (idempotency), รูปแบบข้อผิดพลาด และขีดจำกัดของอัตราการเรียกใช้งาน

อัปเดตเมื่อ ใช้เวลาอ่าน 9 นาที

REST API ของ Clevera ช่วยให้สคริปต์และบริการของคุณทำสิ่งที่เอเจนต์สามารถทำได้ผ่าน MCP: อ่านไลบรารีของคุณ, ขอวิดีโอและบทความ, ส่งออกวิดีโอ, ทำงานบนเว็บไซต์เอกสาร และติดตามงานต่างๆ บทความนี้ครอบคลุมถึง URL พื้นฐาน, การยืนยันตัวตน, ขั้นตอนการขอสำหรับงานที่ต้องชำระเงิน, ข้อผิดพลาด และขีดจำกัดของอัตราการเรียกใช้งาน

ข้อมูลพื้นฐาน
Base URL https://app.clevera.ai/api/v1
การยืนยันตัวตน Authorization: Bearer <token> ด้วย API token (ขึ้นต้นด้วย clv_agent_)
รูปแบบ JSON ทั้งขาเข้าและขาออก ส่ง Accept: application/json และหากมีเนื้อหา (body) ให้ส่ง Content-Type: application/json
Ids ไอดีสาธารณะ เช่น job_… สำหรับงานต่างๆ ให้ใช้ไอดีที่ API ส่งกลับมา

ตรวจสอบโทเค็นด้วย GET /docs/me:

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

คำตอบจะระบุว่าโทเค็นนั้นทำหน้าที่แทนใคร: ชื่อและวันหมดอายุของโทเค็น, บุคคลและบทบาทปัจจุบันของพวกเขา, เวิร์กสเปซ, เว็บไซต์ที่อยู่ในขอบเขต และสิทธิ์ที่ใช้งานได้ในขณะนี้ (สิทธิ์ของโทเค็นที่ถูกจำกัดตามบทบาทปัจจุบันของบุคคลนั้น) ให้เรียกใช้คำสั่งนี้ก่อนเมื่อการเรียกใช้งานถูกปฏิเสธ

เอนด์พอยต์

แต่ละเอนด์พอยต์ต้องการสิทธิ์ที่แสดงไว้ การเรียกใช้งานโดยไม่มีสิทธิ์ดังกล่าวจะส่งคืนค่า 403 forbidden_ability ดู สิทธิ์ของเอเจนต์

ไลบรารีและสื่อ

วิธีการและพาธ สิทธิ์ การทำงาน
GET /create/types any ประเภทวิดีโอและคลิปโซเชียลที่คุณสามารถขอได้
GET /library library:read วิดีโอ, การบันทึก และบทความที่เจ้าของโทเค็นสามารถมองเห็นได้
GET /recordings library:read เฉพาะการบันทึกเท่านั้น
GET /library/{item} library:read รายการเดียว
GET /library/{item}/transcript library:read ถอดความของรายการนั้น
GET /library/{item}/article library:read บทความของรายการนั้น
GET /library/{item}/embed library:read โค้ดสำหรับฝัง (embed code) ของรายการนั้น
GET /materials library:read รูปภาพ, วิดีโอ และ PDF ที่อัปโหลดไว้
POST /materials, POST /materials/import, POST /materials/uploads, POST /materials/uploads/{upload_id}/complete materials:write เพิ่มรูปภาพ, วิดีโอ หรือ PDF (โดยตรง, จาก URL, หรือเป็นการอัปโหลดขนาดใหญ่)

วิดีโอและบทความ

วิธีการและพาธ สิทธิ์ การทำงาน
POST /videos/quotes videos:create ขอใบเสนอราคาวิดีโอจากการบันทึก (type: how_to, product_demo, cleanup, styled_video), บทความจากการบันทึก (article) หรือการแปล (translation)
POST /videos videos:create + credits:spend สร้างวิดีโอที่เสนอราคาไว้ (quote_id)
POST /articles/from-recording videos:create + credits:spend สร้างบทความที่เสนอราคาไว้
POST /videos/translations videos:create + credits:spend สร้างการแปลที่เสนอราคาไว้
POST /clips/quotes videos:create ขอใบเสนอราคาคลิปโซเชียล (ประเภทจาก GET /create/types)
POST /clips videos:create + credits:spend สร้างคลิปโซเชียลที่เสนอราคาไว้
POST /videos/{video_id}/exports videos:export เรนเดอร์ MP4: resolution 1080p (ค่าเริ่มต้น), 2k หรือ 4k; ที่ 60 fps เสมอ ฟรี

งานและเครดิต

วิธีการและพาธ สิทธิ์ การทำงาน
POST /quotes สิทธิ์ของงานนั้น ใบเสนอราคาสำหรับงานทุกประเภท
POST /jobs สิทธิ์ของงานนั้น (+ credits:spend เมื่อชำระเงิน) เริ่มงานที่เสนอราคาไว้
GET /jobs jobs:read รายการงาน
GET /jobs/{job} jobs:read สถานะและผลลัพธ์ของงานหนึ่งรายการ
GET /jobs/{job}/wait jobs:read รอการเปลี่ยนแปลงแทนการ polling
GET /jobs/{job}/events jobs:read เหตุการณ์ความคืบหน้าของงาน
POST /jobs/{job}/cancel jobs:read ยกเลิกงาน หากสายเกินไปจะขึ้นว่า "This job can no longer be canceled."
GET /credits credits:spend หรือ jobs:read ยอดเครดิตของเวิร์กสเปซ

เว็บไซต์เอกสาร

วิธีการและพาธ สิทธิ์ การทำงาน
GET /docs/sites, GET /docs/sites/{site}, GET /docs/sites/{site}/tree, GET /docs/sites/{site}/pages content:read เว็บไซต์ในขอบเขตของโทเค็นและหน้าต่างๆ
GET /docs/sites/{site}/search, GET /docs/pages/{page}, GET /docs/pages/{page}/revisions content:read ค้นหาและอ่านหน้าต่างๆ รวมถึงฉบับร่าง
POST /docs/sites/{site}/articles, PATCH /docs/pages/{page}/article, POST /docs/pages/{page}/review articles:write สร้างและแก้ไขบทความฉบับร่าง, ส่งเพื่อตรวจสอบ บทความที่เผยแพร่แล้วต้องใช้ site:publish ด้วย
PATCH /docs/pages/{page}, DELETE /docs/pages/{page}, POST /docs/sites/{site}/sections, PATCH /docs/sections/{section} structure:write ย้าย, เปลี่ยนชื่อ, ซ่อน และลบหน้าต่างๆ; ส่วนต่างๆ
GET/POST /docs/sites/{site}/site-pages, PUT /docs/site-pages/{page}/body content:read / site-pages:write หน้าหลัก, หน้าติดต่อ และหน้ากฎหมาย
GET/POST /docs/sites/{site}/changelog, PATCH /docs/changelog/{entry} content:read / changelog:write รายการบันทึกการเปลี่ยนแปลง (changelog) ในรูปแบบฉบับร่าง
POST /docs/media, POST /docs/media/uploads media:write อัปโหลดรูปภาพ
POST /docs/sites/{site}/publish, POST /docs/pages/{page}/ready, POST /docs/changelog/{entry}/publish site:publish เผยแพร่สิ่งที่ผู้อ่านเห็น
GET /insights/sites/{site}, …/gaps, …/feedback insights:read ค้นหาช่องว่างของเนื้อหา, คำถามที่ยังไม่ได้ตอบ, ผลตอบรับของหน้าเว็บ
PATCH /docs/sites/{site}/settings, …/appearance, PUT …/navigation, POST …/redirects site:configure การตั้งค่าเว็บไซต์
POST /docs/sites sites:create สร้างเว็บไซต์เอกสาร

ข้อมูลเพิ่มเติมเกี่ยวกับเอเจนต์และเว็บไซต์เอกสาร: เชื่อมต่อ AI เอเจนต์เข้ากับเว็บไซต์เอกสารของคุณ

งานที่มีค่าใช้จ่ายเครดิตจะต้องขอใบเสนอราคาก่อนเสมอ แล้วจึงเริ่มงาน:

  1. ขอใบเสนอราคา POST /videos/quotes (หรือ /clips/quotes) พร้อมสิ่งที่คุณต้องการ คำตอบจะมี quote_id และช่วงของเครดิต ใบเสนอราคามีอายุ 15 นาทีและใช้ได้ครั้งเดียว
  2. ทดสอบการทำงาน (ทางเลือก) ส่งคำสั่งเริ่มงานพร้อม "dry_run": true เพื่อดูว่าจะเริ่มงานได้หรือไม่, ต้องมีการอนุมัติ หรือถูกบล็อก โดยจะไม่มีการเขียนข้อมูลใดๆ
  3. เริ่มงาน POST /videos พร้อม quote_id และส่วนหัว Idempotency-Key คำตอบจะเป็น 202 พร้อมกับงานที่สร้างขึ้น
  4. ติดตามงาน GET /jobs/{job}/wait จนกว่า status ของงานจะเปลี่ยน หรือรอรับการแจ้งเตือนผ่าน webhooks
Quote, then start a how-to video
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>"}'

สถานะของงาน:

สถานะ ความหมาย
queued ยอมรับแล้ว, กำลังจะเริ่มทำงาน
running กำลังดำเนินการ
needs_input รอการดำเนินการจากบุคคล, โดยปกติคือการอนุมัติใน คำขอจากเอเจนต์ งานจะมีลิงก์และวันหมดอายุ
succeeded เสร็จสิ้น งานจะเชื่อมโยงไปยังวิดีโอหรือบทความใหม่
failed ไม่สำเร็จ; งานมี error_code
canceled ยกเลิกแล้ว หรือการอนุมัติถูกปฏิเสธ
expired ไม่มีใครอนุมัติภายใน 24 ชั่วโมง

การที่งานจะเริ่มทันทีหรือต้องรอการอนุมัติจากบุคคลนั้น ขึ้นอยู่กับขีดจำกัดการใช้จ่ายของโทเค็นและการตั้งค่า อนุมัติโดยอัตโนมัติด้านล่าง ดู ควบคุมการใช้จ่ายและการอนุมัติของเอเจนต์

การลองใหม่และความเป็นเอกภาพ (Idempotency)

ส่งส่วนหัว Idempotency-Key (UUID ใหม่ในแต่ละการกระทำ) ในทุกการสร้างและเริ่มงาน หากเครือข่ายหลุดและคุณลองใหม่ด้วยคีย์และเนื้อหาเดิม คุณจะได้รับคำตอบเดิมกลับมาแทนที่จะได้วิดีโอที่สอง คีย์จะถูกจดจำไว้เป็นเวลา 24 ชั่วโมง

รหัส ความหมาย
idempotency_key_reused คีย์เดิมแต่เนื้อหาต่างกัน ให้ใช้คีย์ใหม่สำหรับคำขอใหม่
idempotency_in_progress คำขอแรกด้วยคีย์นี้ยังคงทำงานอยู่ ให้รอและลองใหม่
idempotency_conflict "คีย์ความเป็นเอกภาพนี้ถูกใช้สำหรับคำขออื่นไปแล้ว"

ข้อผิดพลาด

ข้อผิดพลาดทุกรายการมีรูปแบบเดียวกัน พร้อมข้อความที่ระบุว่าต้องทำอย่างไรต่อไป:

{
  "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 เมื่อคุณติดต่อฝ่ายสนับสนุน

HTTP รหัส สาเหตุทั่วไป
401 unauthenticated, token_expired, token_revoked ไม่มีโทเค็น, โทเค็นผิด, หรือโทเค็นหมดอายุหรือถูกเพิกถอน
402 insufficient_credits เวิร์กสเปซไม่มีเครดิตเพียงพอสำหรับใบเสนอราคานี้
403 forbidden_ability, forbidden_role, forbidden_item, ip_not_allowed, live_content_needs_publish, site_paused, forbidden ขาดสิทธิ์, บทบาทของเจ้าของ, การเข้าถึงคอลเลกชัน หรือ IP ไม่อยู่ในรายการอนุญาต
403 plan_locked "Agent API ไม่รวมอยู่ในแผนของเวิร์กสเปซนี้ ต้องเป็นแผน Pro ขึ้นไป"
404 not_found, unknown_kind "ไม่มี … ที่มีไอดีนี้ในขอบเขตของโทเค็นนี้ ให้รายการหรือค้นหาก่อนแล้วใช้ไอดีที่ส่งกลับมา"
409 revision_conflict, quote_used, not_cancelable, idempotency_* เนื้อหาเปลี่ยนไป, ใบเสนอราคาถูกใช้ไปแล้ว, หรือเกิดการชนกันของการลองใหม่
410 quote_expired "ใบเสนอราคานี้หมดอายุแล้ว โปรดขอใบเสนอราคาใหม่"
413 unsupported_media ไฟล์มีขนาดใหญ่เกินไปหรือไม่ใช่ประเภทที่รองรับ
422 validation_failed, invalid_input, quote_mismatch, limit_reached ฟิลด์ไม่ถูกต้อง; details ระบุชื่อฟิลด์นั้น
429 rate_limited, cap_exceeded, busy คำขอมากเกินไป, ถึงขีดจำกัดการใช้จ่าย, หรือเริ่มงานสองงานพร้อมกัน

ข้อความทุกรายการพร้อมวิธีแก้ไข: แก้ไขข้อผิดพลาดของเอเจนต์และ API

ขีดจำกัดของอัตราการเรียกใช้งาน

ขีดจำกัด ค่า ข้อความ
คำขอต่อโทเค็น 300 ต่อนาที "โทเค็นนี้เกินอัตราคำขอที่กำหนด ให้รอและลองใหม่"
คำขอต่อเวิร์กสเปซ 1,200 ต่อนาที, รวมทุกโทเค็น "เวิร์กสเปซนี้เกินอัตราคำขอเอเจนต์ที่กำหนด ให้รอและลองใหม่"
การเขียนต่อโทเค็น 60 ต่อนาที "มีการเขียนจากโทเค็นนี้มากเกินไป ให้รอและลองใหม่"
การเขียนต่อโทเค็นต่อวัน 2,000 "โทเค็นนี้ถึงขีดจำกัดการเขียนรายวันแล้ว ลองใหม่พรุ่งนี้"
การเผยแพร่ต่อโทเค็น 10 ต่อชั่วโมง "โทเค็นนี้ถึงขีดจำกัดการเผยแพร่รายชั่วโมงแล้ว ลองใหม่ภายหลัง"
การเริ่มงานที่ต้องชำระเงิน 20 ต่อชั่วโมงต่อโทเค็น, 100 ต่อวันต่อเวิร์กสเปซ rate_limited พร้อม retry_after
การอัปโหลด 30 ต่อนาที; 500 MB ต่อวันต่อโทเค็น; 25 MB ต่อไฟล์ "มีการอัปโหลดจากโทเค็นนี้มากเกินไป ให้รอและลองใหม่" / "โทเค็นนี้ถึงขีดจำกัดปริมาณการอัปโหลดรายวันแล้ว ลองใหม่พรุ่งนี้"
การเรียกใช้งานโดยไม่มีโทเค็นที่ถูกต้อง 60 ต่อนาทีต่อ IP address "คำขอมากเกินไป ให้รอและลองใหม่"

คำตอบ 429 จะมีส่วนหัว Retry-After และ retry_after (วินาที) ในเนื้อหา ให้รอตามเวลานั้นก่อนลองใหม่ การอ่าน, การขอใบเสนอราคา และการตรวจสอบสถานะไม่มีค่าใช้จ่ายเครดิต

สร้าง API tokenรับโทเค็นสำหรับสคริปต์ของคุณสิทธิ์ของเอเจนต์สิทธิ์ที่แต่ละเอนด์พอยต์ต้องการตั้งค่า webhooksรับทราบเกี่ยวกับงานที่เสร็จสิ้นโดยไม่ต้อง pollingแก้ไขข้อผิดพลาดของเอเจนต์และ APIข้อผิดพลาดทุกรายการและวิธีแก้ไข