بعض الأدوات تجيب فورا (بشكل متزامن)، وبعضها يبدأ مهمة وينهيها في الخلفية. تشرح هذه الصفحة الحالة الثانية: كيف تعرف أن المهمة انتهت وكيف تستلم النتيجة.
رد الإنشاء
الأداة غير المتزامنة تجيب بالرمز 202:
{ "jobId": "...", "status": "...", "state": "pending", "requestId": "req_..." }
الحقل state واحد لكل الأدوات، فاعتمد عليه:
| القيمة | المعنى |
|---|---|
pending | قُبلت ولم تبدأ بعد |
running | قيد التنفيذ |
action_required | تنتظر إجراء منك (مراجعة التقرير: أكّد البيانات المستخرجة) |
completed | انتهت |
partial | انتهت جزئيا: فشلت بعض الملفات (قد يحدث في حزمة المحتوى) |
failed | لم تنجح |
status هو الحالة الخام للأداة (DONE وprocessing وneed_confirm وغيرها). بقي للتوافق، فابنِ التكاملات الجديدة على state.
معرّف المهمة
كل رد مهمة، من أي أداة، يحتوي على الحقل jobId: عند الإنشاء، وفي الحالة، وبعد التأكيد. استعلم عن الحالة به.
قبل الإصدار 1.6.0 كانت الأدوات تعيد المعرّف بأسماء مختلفة (id و_id وcontentGenJobId). تبقى هذه الحقول للتكاملات القائمة لكنها مهملة: استخدم jobId.
الاستعلام عن الحالة
الحالة موجودة في GET /<مسار الأداة>/jobs/{id}:
| الأداة | الحالة |
|---|---|
| تقرير التقييم الكامل | GET /valuation/report/jobs/{id} |
| مراجعة التقرير | GET /valuation/review/jobs/{id} |
| حزمة المحتوى | GET /content/generate/jobs/{id} |
| النصوص | GET /text/generate/jobs/{id} |
| الفيديو | GET /video/create/jobs/{id} |
| الأفاتار | GET /avatar/video/jobs/{id} |
| الصورة | GET /photo/enhance/jobs/{id} |
| المخطط | GET /floorplan/create/jobs/{id} |
GET /pdf/create/jobs/{id} |
- الاستعلام مجاني ولا يُحتسب استدعاء API، لكنه يُحتسب ضمن حد معدل الطلبات. يكفي كل 3 إلى 5 ثوان.
- لا يرى المهمة إلا الحساب الذي أنشأها مفتاحه. المعرّف الذي لا يخصك أو غير المعروف يعيد
404نفسه. - مفتاح الوكيل في الوكالة يرى فقط المهام التي شغّلها بنفسه؛ ومفتاح الوكالة كلها يرى جميع مهام الوكالة.
- يمكن الاستعلام عن المهمة 7 أيام من إنشائها. بعد ذلك يعيد
GET .../jobs/{id}الرمز404، ولا يعود بالإمكان تنزيل ملفات حزمة المحتوى والنصوص والفيديو عبر API. - يحمل رد الحالة الحقلين
statusوstateنفسيهما، ونتيجة الأداة عند جاهزيتها. مهمة حزمة المحتوى أو النصوص أو الفيديو الفاشلة تحملerror، ومهمة الصورmetadata.error: السبب بنص عام.
المخطط ومراجعة التقرير يعالجان المستند فورا: رد 202 يحمل الحالة النهائية مسبقا (completed أو failed أو action_required)، لذا فالاستعلام اختياري.
عندما تنتظرك المهمة
بعد قراءة المستند تتوقف مراجعة التقرير (التقييم) عند action_required وتعيد البيانات المستخرجة في extracted. راجعها وأكّد:
curl -X POST https://developers.grem.capital/api/v1/valuation/review/jobs/JOB_ID/confirm \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{}'
الجسم الفارغ يعني «كل شيء صحيح». لتصحيح قيمة، أرسل الحقول المعدلة فقط داخل extracted بالأسماء نفسها الواردة في الرد (الكائن المتداخل subject يُدمج بعمق مستوى واحد). بعدها تنتقل المهمة إلى running وتصل النتيجة كالمعتاد.
Webhooks بدلا من الاستعلام
كل أداة غير متزامنة ترسل الحدث <أداة>.completed أو <أداة>.failed (وترسل حزمة المحتوى أيضا content.partial). الاشتراك والتحقق من التوقيع: Webhooks.
- يصل الحدث عادة خلال دقيقة من انتهاء المهمة.
- لا تُتابَع المهمة إلا إذا كان الاشتراك في حدثها موجودا عند إنشائها. اشترك مسبقا لا بعد بدء المهمة.
- إذا لم تنته المهمة خلال 30 دقيقة يصل
.failedمعreason: "timeout". قد تنتهي المهمة نفسها لاحقا: الاستعلام يبين حالتها الفعلية.
الملفات الجاهزة
تُنزَّل الملفات عبر GET /artifacts/{path} بالمفتاح نفسه (النطاق tools:artifacts). مجاني، ويدعم Range. قيمة {path} واحدة مما يلي:
| ماذا | المسار |
|---|---|
| ملف من حزمة المحتوى أو النصوص أو الفيديو | v1/ai/assistant/announcement/jobs/{jobId}/artifacts/{artifactId}/download |
| فيديو الأفاتار | v1/ai/assistant/avatar/jobs/{jobId}/artifacts/{artifactId}/download |
| عرض PDF | v1/ai/pdf-generator/files/{id}/download |
| صورة محسنة | v1/ai/photo-enhancement/jobs/{jobId}/download/{variant} |
| PDF تقرير التقييم الكامل | v1/ai/appraisal/reports/{id}/pdf |
| PDF تقدير الإيجار | v1/ai/appraisal/rent/{id}/pdf |
| تقرير المراجعة | v1/ai/appraisal/reviews/{id}/report.pdf أو report.docx |
| تقرير المخطط | v1/ai/floor-plan/jobs/{id}/report.pdf |
| ملف النشرة | v1/ai/flyer/file/{name} |
| مقطوعة للفيديو (استماع) | v1/ai/video-generator/music/{trackId} |
| ملف عادي | المسار /files/... من رد الأداة |
معرّفات ملفات حزمة المحتوى موجودة في الحقل artifacts من حالة المهمة. ملفات حزمة المحتوى والنصوص والفيديو متاحة فقط للمهام التي أنشأها الحساب نفسه عبر API، ولمدة 7 أيام.
curl -L -o video.mp4 \
"https://developers.grem.capital/api/v1/artifacts/v1/ai/assistant/announcement/jobs/JOB_ID/artifacts/ARTIFACT_ID/download" \
-H "Authorization: Bearer gsk_live_xxx"
لعرض PDF أيضا الحقل link: العنوان المباشر للمستند.
مقالات ذات صلة
- الأدوات عبر API: أي الأدوات متزامنة وأيها غير متزامنة.
- Webhooks: استلام النتائج دون استعلام.
- الملفات: رفع الصور للعقارات والأدوات.