استخدام Clevera REST API

استدعِ Clevera من نصوصك البرمجية الخاصة: عنوان URL الأساسي، ومصادقة رمز الحامل (bearer-token)، ونقاط النهاية (endpoints) والصلاحيات التي يحتاجها كل منها، وتدفق "عرض السعر ثم البدء" للعمل المدفوع، وتماثل العمليات (idempotency)، وتنسيق الخطأ، وحدود المعدل.

تم التحديث 20 أكتوبر 2026وقت القراءة 8 دقائق

تتيح لك واجهة برمجة تطبيقات Clevera REST لنصوصك وخدماتك البرمجية القيام بما يمكن للوكيل القيام به عبر MCP: قراءة مكتبتك، وطلب مقاطع الفيديو والمقالات، وتصدير مقاطع الفيديو، والعمل على مواقع التوثيق، ومتابعة المهام. تغطي هذه المقالة عنوان URL الأساسي، والمصادقة، وتدفق الطلب للعمل المدفوع، والأخطاء، وحدود المعدل.

الأساسيات


عنوان URL الأساسي	`https://app.clevera.ai/api/v1`
المصادقة	`Authorization: Bearer <token>` باستخدام رمز API (يبدأ بـ `clv_agent_`)
التنسيق	JSON للإدخال والإخراج. أرسل `Accept: application/json`، ومع وجود نص أساسي، أرسل `Content-Type: application/json`.
المعرفات	معرفات عامة، مثل `job_…` للمهام. استخدم المعرفات التي تعيدها واجهة برمجة التطبيقات.

تحقق من الرمز باستخدام 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`	أي	أنواع مقاطع الفيديو والمقاطع الاجتماعية التي يمكنك طلبها.
`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 إطاراً في الثانية. مجاني.

المهام والأرصدة

الطريقة والمسار	الصلاحية	ما تفعله
`POST /quotes`	صلاحية العمل	عرض سعر لأي نوع من المهام.
`POST /jobs`	صلاحية العمل (+ `credits:spend` عند الدفع)	بدء مهمة تم عرض سعرها.
`GET /jobs`	`jobs:read`	سرد المهام.
`GET /jobs/{job}`	`jobs:read`	حالة ونتيجة مهمة واحدة.
`GET /jobs/{job}/wait`	`jobs:read`	انتظار تغيير بدلاً من الاستطلاع.
`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 بمواقع التوثيق الخاصة بك.

طلب عمل مدفوع

العمل الذي يكلف أرصدة يتطلب دائماً عرض سعر أولاً، ثم البدء:

عرض السعر. POST /videos/quotes (أو /clips/quotes) بما تريده. تحتوي الإجابة على quote_id ونطاق الرصيد. عرض السعر صالح لمدة 15 دقيقة ويمكن استخدامه مرة واحدة.
اختيارياً، قم بإجراء تشغيل تجريبي. أرسل البدء مع "dry_run": true لمعرفة ما إذا كان سيبدأ، أو يحتاج إلى موافقة، أو سيتم حظره. لا يتم كتابة أي شيء.
ابدأ المهمة. POST /videos مع quote_id ورأس Idempotency-Key. الإجابة هي 202 مع مهمة.
تابع المهمة. GET /jobs/{job}/wait حتى تتغير status المهمة، أو استمع إلى خطافات الويب.

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`	"واجهة برمجة تطبيقات الوكيل ليست ضمن خطة مساحة العمل هذه. إنها متاحة في خطة 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`	الكثير من الطلبات، أو حد إنفاق، أو عمليتان للبدء في وقت واحد.

كل رسالة، مع الحل: إصلاح أخطاء الوكيل وواجهة برمجة التطبيقات.

حدود المعدل

الحد	القيمة	الرسالة
الطلبات لكل رمز	300 في الدقيقة	"تجاوز هذا الرمز معدل طلباته. انتظر وأعد المحاولة."
الطلبات لكل مساحة عمل	1,200 في الدقيقة، لجميع الرموز معاً	"تجاوزت مساحة العمل هذه معدل طلبات الوكيل. انتظر وأعد المحاولة."
عمليات الكتابة لكل رمز	60 في الدقيقة	"الكثير من عمليات الكتابة من هذا الرمز. انتظر وأعد المحاولة."
عمليات الكتابة لكل رمز يومياً	2,000	"وصل هذا الرمز إلى حد الكتابة اليومي. حاول مرة أخرى غداً."
عمليات النشر لكل رمز	10 في الساعة	"وصل هذا الرمز إلى حد النشر بالساعة. حاول مرة أخرى لاحقاً."
البدء المدفوع	20 في الساعة لكل رمز، 100 يومياً لكل مساحة عمل	`rate_limited` مع `retry_after`
التحميلات	30 في الدقيقة؛ 500 ميجابايت يومياً لكل رمز؛ 25 ميجابايت لكل ملف	"الكثير من التحميلات من هذا الرمز. انتظر وأعد المحاولة." / "وصل هذا الرمز إلى حجم التحميل اليومي. حاول مرة أخرى غداً."
الاستدعاءات بدون رمز صالح	60 في الدقيقة لكل عنوان IP	"الكثير من الطلبات. انتظر وأعد المحاولة."

تحتوي إجابة 429 على رأس Retry-After و retry_after (بالثواني) في النص الأساسي. انتظر تلك المدة قبل إعادة المحاولة. عمليات القراءة وعروض الأسعار وفحوصات الحالة لا تكلف أرصدة.

إنشاء رمز APIاحصل على رمز لنصك البرمجي.صلاحيات الوكيلالصلاحية التي تحتاجها كل نقطة نهاية.إعداد خطافات الويبتعرف على المهام المنتهية دون استطلاع.إصلاح أخطاء الوكيل وواجهة برمجة التطبيقاتكل خطأ وحله.

الأساسيات#

نقاط النهاية#

المكتبة والمواد#

مقاطع الفيديو والمقالات#

المهام والأرصدة#

مواقع التوثيق#

طلب عمل مدفوع#

عمليات إعادة المحاولة وتماثل العمليات#

الأخطاء#

حدود المعدل#

ذات صلة#