الأدوات نفسها التي تستخدمها في اللوحة متاحة برمجيا. ويحتسب كل استدعاء من محفظتك تماما كما يحتسب العمل عبر الواجهة: الاشتراك أولا، ثم الحزمة، ثم الدفع حسب الاستخدام. أما القراءات (GET) فلا تحتسب أبدا.
العنوان الأساسي: https://developers.grem.capital/api/v1.
الأدوات
| الاستدعاء | النطاق المطلوب | كيف يعمل |
|---|---|---|
POST /valuation/express | أي مفتاح | متزامن |
POST /valuation/report | tools:valuation | مؤجل |
POST /valuation/rent | tools:rent | متزامن |
POST /valuation/review | tools:review | مؤجل، مع ملف |
POST /content/generate | tools:contentgen | مؤجل |
POST /text/generate | tools:text | مؤجل |
POST /avatar/video | tools:avatar | مؤجل |
POST /video/create | tools:video | مؤجل، مع ملف |
POST /photo/enhance | tools:photo | مؤجل، مع ملف |
POST /floorplan/create | tools:floorplan | مؤجل، مع ملف |
POST /draft/extract | tools:draft | متزامن، مع ملف |
POST /site/create | tools:sitegen | متزامن، يتطلب إعلانا |
POST /pdf/create | tools:pdf | مؤجل، يتطلب إعلانا |
إن كان المفتاح بلا النطاق المطلوب أعاد الاستدعاء 403. وتمنح النطاقات عند إنشاء المفتاح في اللوحة: أدوات الذكاء الاصطناعي ← API ← المفاتيح. انظر المصادقة.
الاستدعاءات المتزامنة
تعيد الأداة المتزامنة 200 مع النتيجة الجاهزة في جسم الرد:
curl -X POST https://developers.grem.capital/api/v1/valuation/rent \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{"propertyCategory":"apartment","totalArea":50,"city":"Kyiv"}'
الاستدعاءات المؤجلة
الأدوات الطويلة (تقرير التقييم، والنصوص، والصورة، والفيديو، والأفاتار، ومخطط الطابق، وPDF) تعيد 202 ومقبضا للمهمة:
{ "jobId": "…", "status": "pending", "requestId": "req_…" }
استعلم عن الحالة على GET /<مسار الأداة>/jobs/{jobId}:
curl -H "Authorization: Bearer gsk_live_xxx" \
https://developers.grem.capital/api/v1/content/generate/jobs/JOB_ID
يحمل الرد حقل status. والحالات النهائية هي completed (أو done أو success) وfailed. وما دامت المهمة جارية أعد الطلب كل بضع ثوان.
الاستعلام مجاني: فطلب GET لا يعد استدعاء API ولا يحتسب. ومع ذلك يبقى الاشتراك في حدث أفضل من الاستعلام المكثف - انظر Webhooks.
وكل مهمة تخص المفتاح الذي أنشأها. أما jobId يخص غيرك فيعيد 404 دائما، حتى لو كانت تلك المهمة موجودة.
أدوات تستقبل ملفا
الاستدعاءات الموسومة «مع ملف» تقبل multipart/form-data: توضع الخيارات بصيغة JSON في حقل نصي اسمه data، والملف نفسه جزء مستقل.
curl -X POST https://developers.grem.capital/api/v1/photo/enhance \
-H "Authorization: Bearer gsk_live_xxx" \
-F 'data={"mode":"enhance"}' \
-F "image=@room.jpg"
وإرسال JSON عادي إلى إحداها يعيد 400 مع ملاحظة بأن المتوقع هو multipart/form-data.
أدوات تتطلب إعلانا
يبني مولد المواقع ومولد PDF العرض من إعلان قائم، لذا يجب أن يحمل جسم الطلب objectId (أو collectionId للمجموعة). ويجب أن يكون الإعلان لك - فمعرف غيرك يعيد خطأ صلاحية.
curl -X POST https://developers.grem.capital/api/v1/pdf/create \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{"objectId":"64f…","language":"en"}'
الملفات الجاهزة
تعود النتائج (PDF وفيديو وصور وصفحات) روابط على نطاق GREM. نزّلها عبر GET /artifacts/… بالمفتاح نفسه - انظر الملفات والنتائج.
إعادة المحاولة بلا تكرار
إنشاء المهمة آمن لإعادة المحاولة: أرسل ترويسة Idempotency-Key، فتعيد المحاولة بالمفتاح نفسه النتيجة الأصلية بدل احتساب المبلغ مرتين. التفاصيل في الحياد التكراري.
ماذا تعني الأخطاء
402- لا يكفي المال في المحفظة أو استنفدت حصة الباقة.403- المفتاح بلا نطاق لهذه الأداة.429- بلغ حد المعدل؛ أعد المحاولة بعد المهلة الواردة في ترويسةRetry-After.
والقائمة الكاملة في الأخطاء.
مقالات ذات صلة
- بداية سريعة - أول استدعاء في خمس دقائق.
- Webhooks - استلام النتيجة الجاهزة بدل الاستعلام.
- الملفات والنتائج - رفع الصور وتنزيل المخرجات.