Occlusia للبرامج: واجهة API وأدوات الذكاء الاصطناعي

كل ما يفعله تطبيق الويب يستطيع برنامج أن يفعله: فتح نموذج، وسرد كائناته ومناظره، وتغيير إعداداتها، وتطبيق تهيئة، ومعاينة منظر، والتصدير إلى SVG أو DXF أو PDF أو صور. إنه محرك تطبيق الويب نفسه: الرسومات هي رسومات التطبيق بايتًا ببايت، وكذلك رفضاته وأسعاره.

• MCP: تتصل أداة ذكاء اصطناعي — Claude أو ChatGPT أو مساعد محرر — بـ https://api.occlusia.app/v1/mcp بالعنوان وحده، وتوافق أنت عليها على occlusia.app. ثم تعمل على نماذجك بكلماتك أنت.
• واجهة REST API: https://api.occlusia.app/v1/engine — المحرك لسكربت أو خادم أو مهمة تكامل مستمر أو تطبيق خاص بك، بمفتاح API أو عبر OAuth.

أعطِ أداة الذكاء الاصطناعي لديك عنوان خادم MCP الخاص بـ Occlusia. في المرة الأولى، تحيلك إلى occlusia.app: سجّل الدخول إن لزم، وتحقّق من التطبيق الذي يطلب وما الذي سيتمكن من فعله، ثم اسمح له. لا يوجد مفتاح لنسخه.

https://api.occlusia.app/v1/mcp

• Claude (claude.ai، وتطبيقات سطح المكتب والهاتف المحمول): Settings، Connectors، Add custom connector، ثم العنوان أعلاه.
• ChatGPT: أضف خادم MCP مخصصًا بالعنوان أعلاه، مع OAuth طريقةً للمصادقة.
• Claude Code: claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp، ثم /mcp لتسجيل الدخول.
• Cursor وVS Code والأدوات الأخرى: أضف خادم MCP بعيدًا (Streamable HTTP) بالعنوان؛ فتسجّل دخولك بالطريقة نفسها.

يظهر كل تطبيق تسمح له في حسابك ضمن التطبيقات المرتبطة، مع ما يُسمح له بفعله ووقت آخر استخدام له. افصله من هناك فيتوقف فورًا. يرسل إليك Occlusia بريدًا إلكترونيًا في المرة الأولى التي يرتبط فيها تطبيق.

كل أمر أداة يمكن للذكاء الاصطناعي استدعاؤها: فتح نموذج، وسرد كائناته، وتعيين تهشير، وإنشاء معاينة — تُعاد كصورة يراها النموذج —، والتصدير. لكل أداة عنوان، وتذكر ما إذا كانت تقرأ فقط أو تغيّر شيئًا أو تستبدل ملفًا، وتذكر تكلفتها.

• مساحة عمل: ما يفتحه الذكاء الاصطناعي ويضبطه ويصدّره يبقى في مساحة عملك من طلب إلى آخر، ومن محادثة إلى أخرى، ما دامت مستخدمة. تنتهي بعد مدة من عدم الاستخدام، أو عندما يعيد الذكاء الاصطناعي تعيينها.
• ملفاتك: يعطيك الذكاء الاصطناعي صفحة لإفلات نموذجك عليها — نموذج .skp أو .ifc أو .fbx أو .occs، أو مشروع .occp —، أو يجلبه من رابط عام؛ ويعيد إليك ما صدّره على شكل روابط تنزيل.
• حسابك: رصيدك، وسجلّه، والأسعار، ومشترياتك. عندما يوشك الرصيد على النفاد، يمكن للذكاء الاصطناعي أن يُعدّ عملية شراء: يعطيك رابطًا إلى occlusia.app، حيث تراجعها وتدفع — ولا يشتري الذكاء الاصطناعي أي شيء أبدًا.
• دليل ومرجع يقرؤهما الذكاء الاصطناعي بنفسه (سير العمل، وكل إعداد وقيمه)، ومطالبات جاهزة: إنشاء رسومات من نموذج، وتصدير مجموعة رسومات، ومراجعة الحساب.

يتعامل الخادم مع كل إصدارات MCP الحالية (2026-07-28، ومن 2025-11-25 رجوعًا إلى 2025-03-26). ويعمل مفتاح API أيضًا، في الأدوات التي ترسله كترويسة:

claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp \
  --header "Authorization: Bearer occ_sk_…"

يسجّل السكربت أو الخادم أو مهمة التكامل المستمر الدخول بمفتاح API. أنشئ واحدًا في حسابك، ضمن مفاتيح API: اسم، ومدة صلاحية، وتسجيل دخول خلال الدقائق الأخيرة. يُعرض المفتاح مرة واحدة؛ ولا يحتفظ Occlusia إلا ببصمة له.

• يقرأ المفتاح حسابك وينفق رصيدك؛ ولا يدير الحساب أبدًا.
• تسرد صفحة مفاتيح API كل مفتاح باسمه وآخر أربعة أحرف منه، مع وقت آخر استخدام له والعنوان الذي استُخدم منه. يحتفظ الحساب بـ 20 مفتاحًا على الأكثر.
• إلغاء المفتاح يوقف فورًا كل برنامج يستخدمه. يرسل إليك Occlusia بريدًا إلكترونيًا في كل مرة يُنشأ فيها مفتاح.

يشغّل https://api.occlusia.app/v1/engine المحرك على خوادم Occlusia، وكل طلب يحمل مفتاحًا — Authorization: Bearer occ_sk_… — أو رمز وصول تطبيق. الجلسة محرك خاص بك بملفاته الخاصة: ارفع نموذجًا، وشغّل الأوامر، ونزّل ما كتبته، ثم أنهِ الجلسة.

KEY=occ_sk_…
API=https://api.occlusia.app/v1/engine
S=$(curl -s -X POST $API/sessions -H "Authorization: Bearer $KEY" | jq -r .id)
curl -T house.skp $API/sessions/$S/files/house.skp -H "Authorization: Bearer $KEY"
curl $API/sessions/$S/commands/model.open -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' -d '{"path":"house.skp"}'
curl $API/sessions/$S/commands/export -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' -d '{"format":"pdf","sections":"Section AA","out":"section.pdf"}'
curl -o section.pdf $API/sessions/$S/files/section.pdf -H "Authorization: Bearer $KEY"
curl -X DELETE $API/sessions/$S -H "Authorization: Bearer $KEY"

المسارات، تحت /v1/engine؛ و… تعني /sessions/{id}:

POST /sessions

يفتح جلسة. يحتفظ الحساب بـ 3 جلسات في وقت واحد؛ وتنتهي الجلسة بعد 15 دقيقة دون استخدام أو بعد 8 ساعات.

PUT …/files/{name}

يرفع ملفًا، في متن الطلب الخام: 512 ميغابايت على الأكثر، و2 غيغابايت لكل جلسة.

POST …/commands/{command}

يشغّل أمرًا، ومعاملاته في متن JSON؛ والإجابة هي إجابة الأمر. مع Prefer: respond-async تُعاد مهمة فورًا.

GET …/jobs/{job}

مهمة: قيد التشغيل، أو منتهية مع نتيجتها، أو فاشلة مع خطئها.

GET …/events

ما يفعله المحرك، كأحداث يرسلها الخادم: التقدم، والرسائل، والتصديرات.

GET …/files/{name}

ينزّل ملفًا من الجلسة. يسردها GET …/files، ويحذف DELETE أحدها.

POST …/links

رابط يرفع ملفًا واحدًا أو ينزّله لمدة 15 دقيقة، من دون المفتاح؛ ورابط الرفع إذا فُتح في متصفح يكون صفحة لإفلات الملف عليها.

DELETE /sessions/{id}

ينهي الجلسة؛ وتُحذف ملفاتها معها.

GET /commands

كل أمر مع JSON Schema الخاص به؛ والواجهة كاملة بصيغة OpenAPI في /openapi.json.

يسمّي معامل الملف ملفًا من الجلسة — "path": "house.skp"، "out": "set.pdf" —، وليس مسارًا على الخادم أبدًا. تُسمّى الكائنات كما في متصفح النموذج — بالاسم أو بالمسار (Walls/South wall) —، والمناظر بأسمائها. يُشغَّل أمر واحد في كل مرة في الجلسة؛ أما ما يتطلب حسابًا — فتح نموذج، أو رسم، أو تصدير — فيُشغَّل منه اثنان في وقت واحد لكل حساب، وينتظر دوره حتى دقيقة واحدة، بينما لا تنتظر القائمة أو الإعداد أبدًا. 600 طلب في الدقيقة لكل مفتاح.

• عدم تكرار التنفيذ: أرسل Idempotency-Key مع الأمر، فتُجاب إعادة المحاولة بعد ضياع الإجابة من التشغيل الأول — فلا يُشغَّل الأمر مرتين ولا يُحتسب مرتين أبدًا.
• معرّفات الطلبات والحدود: تحمل كل إجابة X-Request-Id (معرّفك أنت، إن أرسلت واحدًا) وRateLimit-Limit وRateLimit-Remaining وRateLimit-Reset.
• الحساب: تقرؤه GET /v1/auth/me و/v1/account/credits و/v1/account/credits/history و/v1/account/credits/purchases بالمفتاح نفسه.
• إعداد التصدير: يقرأ export.config وexport.setup صفحة PDF لكل منظر وموضع الرسم على اللوحة ويغيّرانهما، كما تفعل نافذة التصدير.

كل رفض هو {"error": {"code", "message"}} مع رمز ثابت: invalid_api_key (401)، insufficient_credits (402)، session_not_found (404)، invalid_params (422)، rate_limited وsession_limit وcloud_limit (429: نفد حدّ الوصول المبكر حتى Retry-After الخاص به)، busy (503: أعد المحاولة بعد Retry-After الخاص به)، credits_unavailable (503: لم يُنفَّذ شيء، أعد المحاولة)، ورموز الأمر نفسه حين يرفض.

يمكن لتطبيق خاص بك أن يعمل باسم مستخدميه على حساباتهم في Occlusia عبر OAuth 2.1: تدفق رمز التفويض مع PKCE (S256)، وعملاء عامّون. توجد البيانات الوصفية لخادم التفويض في https://api.occlusia.app/.well-known/oauth-authorization-server؛ سجّل عميلك هناك، أو عرّفه بعنوان https لمستند بيانات وصفية للعميل.

• النطاقات: engine — الفتح والإعداد والرسم والتصدير، مع إنفاق رصيد المستخدم —، وaccount — قراءة الحساب ورصيده ومشترياته.
• اطلب المورد الذي تستدعيه (resource=https://api.occlusia.app/v1/engine أو …/v1/mcp): لا يعمل رمز الوصول إلا هناك.
• يدوم رمز الوصول ساعة واحدة؛ وتتجدد رموز التحديث عند كل استخدام. يرى المستخدم تطبيقك ضمن التطبيقات المرتبطة ويمكنه فصله من هناك.

• يخزّن Occlusia مفتاح API كبصمة، وليس كما هو أبدًا: لا يمكن عرض المفتاح المفقود مجددًا، بل إلغاؤه فقط.
• يحمل التطبيق المرتبط رموزًا لا يحتفظ بها Occlusia إلا كبصمات؛ ولا تفتح إلا ما سمحت به، ولا تفتح شيئًا بمجرد أن تفصل التطبيق.
• تعمل كل جلسة API في محرك خاص بها، تحت مستخدم نظام خاص بها، ومن دون أي شبكة سوى خدمات Occlusia. تُحذف ملفاتها عند انتهائها.
• الملف الذي يُجلب من رابط يأتي من الإنترنت العام فقط، ولا يأتي أبدًا من شبكة خاصة.
• يتطلب إنشاء مفتاح أو ربط تطبيق تسجيل دخول خلال الدقائق الأخيرة، ويرسل إليك Occlusia بريدًا إلكترونيًا في كل مرة.