من نموذج إلى رسم، عبر HTTP

• حساب Occlusia ومفتاح API، يُنشأ ضمن مفاتيح API في حسابك. احتفظ بالمفتاح في متغير بيئة: تقرأ الأمثلة OCCLUSIA_API_KEY.
• نموذج: ملف .skp محفوظ بواسطة SketchUp 2021 أو أحدث، أو ملف .ifc أو .fbx أو .occs، بحد أقصى 512 MB.
• معيارك الرسومي في صورة تكوين، مصدَّر من Occlusia Studio عبر Export › Configuration (.occc) — أو لا شيء، فيُرسم النموذج بالإعدادات الافتراضية.
• نقاط، أو حساب في الوصول المبكر: فتح النموذج وكل عملية تصدير يكلّفان نقاطًا (API وMCP، التكلفة).

1. 01

   افتح جلسة

   يبدأ POST /sessions محركًا خاصًا بك، مسجَّلًا دخوله إلى حسابك، ويجيب بمعرّفه id. يحتفظ الحساب بـ 3 جلسات في وقت واحد؛ وتنتهي الجلسة بعد 15 دقيقة دون استخدام، أو بعد 8 ساعات.

2. 02

   ارفع الملفات

   PUT /sessions/{id}/files/{name}، مع الملف في صورة متن خام للطلب: النموذج وتكوينه. والاسم هو اسم الملف في الجلسة، وليس مسارًا على الخادم أبدًا.

3. 03

   افتح واضبط

   يفتح الأمر model.open مع {"path": "house.skp"} النموذج ويجيب بمناظره في sections. ويطبّق config.set مع {"path": "standard.occc"} التكوين؛ والتكوين الذي يخالف الصيغة يُرفض كله، مع كل الأخطاء.

4. 04

   انظر، إن احتجت

   يجيب preview.render بمنظر في صورة PNG أو JPEG أو SVG نفسه، بحد أقصى 2048 بكسل على ضلعه الأطول. ولا يحتاج التصدير إليه.

5. 05

   صدّر

   export مع format — svg أو dxf أو pdf أو png أو jpg —، وsections المراد رسمها — اسم منظر، أو قائمة بها — وout: ملف لرسم واحد، أو مجلد لعدة رسومات. ويجعل merged منها ملف PDF واحدًا.

6. 06

   نزّل، ثم أنهِ الجلسة

   يُنزّل GET /sessions/{id}/files/{name} ما كتبه التصدير؛ ويُنهي DELETE /sessions/{id} الجلسة، وتُحذف ملفاتها معها.

KEY=occ_sk_…                                  # Account › API keys
API=https://api.occlusia.app/v1/engine
AUTH="Authorization: Bearer $KEY"
JSON="Content-Type: application/json"

# 1. A session: an engine of your own, with its own files
S=$(curl -s -X POST $API/sessions -H "$AUTH" | jq -r .id)

# 2. The model and your graphic standard
curl -T house.skp $API/sessions/$S/files/house.skp -H "$AUTH"
curl -T standard.occc $API/sessions/$S/files/standard.occc -H "$AUTH"

# 3. Open the model (1 credit), apply the configuration (free)
curl $API/sessions/$S/commands/model.open -H "$AUTH" -H "$JSON" -d '{"path":"house.skp"}'
curl $API/sessions/$S/commands/config.set -H "$AUTH" -H "$JSON" -d '{"path":"standard.occc"}'

# 4. Export one view as DXF (1 credit per drawing)
curl $API/sessions/$S/commands/export -H "$AUTH" -H "$JSON" \
     -d '{"format":"dxf","sections":"Section A-A","out":"section-a.dxf"}'

# 5. Download it, then end the session: its files are deleted with it
curl -o section-a.dxf $API/sessions/$S/files/section-a.dxf -H "$AUTH"
curl -X DELETE $API/sessions/$S -H "$AUTH"

تصدّر الأمثلة المنظر الأول للنموذج. ويسردها sections.list كلها ويقول أيها نشط؛ ويسرد objects.list وannotations.list وlevels.list بقية النموذج.

• يصدّر "sections": "Section A-A" منظرًا واحدًا؛ و["Section A-A", "Ground floor plan"] عدة مناظر، لكل منها ملفه في المجلد out — أو ملف PDF واحد مع "merged": true.
• يحدد page صفحة PDF لكل منظر — format وorientation وscale_mode بقيمة fit أو custom مع scale_denominator (1:N) وmargins_mm —، ويحدد pages منظرًا واحدًا في كل صفحة؛ ويحدد image حجم صورة PNG أو JPEG أو مقياسها، والدقة والخلفية والجودة.
• يقرأ export.config إعداد صفحة كل منظر، ويغيّره export.setup دون تصدير، كما تفعل نافذة التصدير.
• يجيب التصدير بالملفات التي كتبها وبما كلّفه؛ ويسرد GET /sessions/{id}/files ملفات الجلسة.

كل إعداد يحمله التكوين يمكن ضبطه أيضًا أمرًا بعد أمر: object.set لكائن، وobject.apply_preset لإعداد مسبق للتهشير، وlayers.create وlayers.update لطبقات DXF، وsection.set لمنظر، وannotation.set وlevel.set للملاحظات والمناسيب. ويسرد engine.schema كل إعداد وقيمه؛ ويجيب config.get بالتكوين كاملًا، لحفظه ملف .occc.

قد تستغرق مجموعة PDF دقائق. أرسل أمرها مع Prefer: respond-async: فيجيب بـ 202 ومهمة فورًا، ويقول GET /sessions/{id}/jobs/{job} إن كانت المهمة جارية، أو انتهت بنتيجتها، أو فشلت بخطئها. ويبثّ GET /sessions/{id}/events ما يفعله المحرك على هيئة أحداث مرسَلة من الخادم: progress وmessage وexport وjob وended.

• كل رفض هو {"error": {"code", "message"}}، برمز ثابت وحالة HTTP المقابلة له.
• يحمل 429 مع cloud_limit أو rate_limited، و503 مع busy، الترويسة Retry-After: انتظر تلك المدة، ثم أرسل الطلب نفسه مجددًا.
• أرسل Idempotency-Key مع الأمر: فيُجاب عن إعادة المحاولة بعد جواب ضائع من التشغيل الأول — لا تُنفَّذ ولا تُحتسب مرتين أبدًا.
• يحمل كل جواب X-Request-Id: اذكره مع أي سؤال عن طلب.

GET /v1/engine

إصدار المحرك وبناؤه، دون مفتاح.

GET /v1/engine/openapi.json

واجهة API كاملة بصيغة OpenAPI.

GET /v1/engine/commands

كل أمر، مع معاملاته بصيغة JSON Schema.

كل مسار وحد ورمز خطأ مسرود في API وMCP، ضمن REST API.