דלג לתוכן
מרכז העזרה של Clevera

שימוש ב-REST API של Clevera

בצע קריאות ל-Clevera מהסקריפטים שלך: כתובת בסיס (base URL), אימות באמצעות bearer-token, נקודות קצה (endpoints) וההרשאות הנדרשות לכל אחת, תהליך הצעת המחיר ולאחריו ההפעלה עבור עבודה בתשלום, אידמפוטנטיות, פורמט שגיאות ומגבלות קצב.

עודכן ב-7 דקות קריאה

ה-REST API של Clevera מאפשר לסקריפטים ולשירותים שלך לבצע פעולות שסוכן יכול לבצע דרך MCP: קריאת הספרייה שלך, בקשת סרטונים ומאמרים, ייצוא סרטונים, עבודה על אתרי תיעוד ומעקב אחר משימות. מאמר זה מכסה את כתובת הבסיס, אימות, תהליך הבקשה לעבודה בתשלום, שגיאות ומגבלות קצב.

יסודות
כתובת בסיס (Base URL) https://app.clevera.ai/api/v1
אימות Authorization: Bearer <token> עם אסימון API (מתחיל ב-clv_agent_)
פורמט JSON בכניסה וביציאה. שלח Accept: application/json ועם גוף בקשה, 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

התשובה מציינת בשם מי האסימון פועל: שם האסימון ותוקפו, האדם ותפקידו הנוכחי, סביבת העבודה, האתרים שבטווח וההרשאות הפעילות כרגע (הרשאות האסימון מצומצמות לתפקיד הנוכחי של האדם). בצע קריאה זו תחילה כאשר קריאה נדחית.

נקודות קצה (Endpoints)

כל נקודת קצה דורשת את ההרשאה המוצגת. קריאה לאחת ללא הרשאה מחזירה 403 forbidden_ability. ראה הרשאות סוכן.

ספרייה וחומרים

שיטה ונתיב הרשאה מה זה עושה
GET /create/types כל הרשאה סוגי הסרטונים וקליפים חברתיים שניתן לבקש.
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 קוד ההטמעה שלו.
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 ביטול משימה. מאוחר מדי: "לא ניתן לבטל משימה זו יותר."
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 רשומות יומן שינויים כטיוטות.
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-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 "ה-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 "יותר מדי בקשות. המתן ונסה שוב."

תשובת 429 כוללת כותרת Retry-After ו-retry_after (שניות) בגוף הבקשה. המתן זמן זה לפני ניסיון חוזר. קריאות, הצעות מחיר ובדיקות סטטוס אינן עולות קרדיטים.

יצירת אסימון APIקבל אסימון עבור הסקריפט שלך.הרשאות סוכןאיזו הרשאה כל נקודת קצה דורשת.הגדרת webhooksקבל עדכונים על משימות שהסתיימו ללא polling.תיקון שגיאות סוכן ו-APIכל שגיאה והתיקון שלה.