نقاط النهاية هذه تعمل في هذه المعاينة لكنها ليست عامة بعد — لا يوجد إصدار لمفاتيح واجهة برمجة التطبيقات بعد، وقد يتغير الشكل قبل الإصدار المستقر.
انضم إلى قائمة انتظار واجهة برمجة التطبيقاتنظرة عامة
يوفر هذا التطبيق واجهة برمجة تطبيقات صغيرة للمهام من نفس المصدر: ارفع صورة، أرسل مهمة ترميم أو تكبير، ثم استطلع نتيجتها. لا توجد مفاتيح واجهة برمجة تطبيقات بعد — كل طلب مقيّد بملف تعريف ارتباط جلسة الضيف الخاص بمتصفحك.
- عنوان URL الأساسي
- /apiجميع المسارات أدناه نسبية إلى هذا الأساس من نفس المصدر — لا يوجد مضيف واجهة برمجة تطبيقات منفصل يجب إعداده.
- المصادقة
- مقيّدة بالجلسة عبر ملف تعريف ارتباط httpOnly يُصدر عند المتابعة كضيف. لا توجد مفاتيح واجهة برمجة تطبيقات بعد (راجع "المخطط له" أدناه).
ضمان العقد: قيمة result_url الخاصة بأي مهمة تكون دائمًا image_url صالحة — يمكنك إرسالها مباشرة إلى /api/restore أو /api/upscale لسلسلة عملية أخرى (هذه بالضبط الطريقة التي تعمل بها "تكبير هذه الصورة" بعد الترميم).
/api/uploadsرفع صورة
يرفع ملف صورة واحدًا ويعيد عنوان URL لأصل من نفس المصدر يمكنك تمريره كـ image_url إلى الترميم أو التكبير.
نص الطلب
| الاسم | النوع | مطلوب | الحدود | الوصف |
|---|---|---|---|---|
| file | binary (multipart/form-data) | نعم | — | ملف الصورة، يُرسل بصيغة multipart/form-data. |
نص الاستجابة
| الاسم | النوع | مطلوب | الحدود | الوصف |
|---|---|---|---|---|
| image_url | string | نعم | — | عنوان URL لأصل من نفس المصدر يُعاد من عملية رفع سابقة — الشكل الوحيد المقبول لـ image_url. |
| bytes | number | نعم | 0–9007199254740991 | حجم الملف المخزَّن بالبايت. |
| mime | string | نعم | — | نوع MIME المكتشف للملف المخزَّن (وهو الموثوق — وليس النوع الذي يعلنه العميل). |
مثال استجابة 201
{
"image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"bytes": 2458112,
"mime": "image/jpeg"
}أمثلة الكود
curl -X POST 'https://your-app.example.com/api/uploads' \
-F "file=@photo.jpg"/api/restoreإنشاء مهمة ترميم
يبدأ مهمة ترميم غير متزامنة لصورة تم رفعها مسبقًا. يعيد فورًا مرجع مهمة بحالة pending — استطلع التقدم عبر GET /api/jobs/{job_id}.
نص الطلب
| الاسم | النوع | مطلوب | الحدود | الوصف |
|---|---|---|---|---|
| image_url | string | نعم | /api/mock-assets/<uuid> | عنوان URL لأصل من نفس المصدر يُعاد من عملية رفع سابقة — الشكل الوحيد المقبول لـ image_url. |
| user_hint | string | لا | max 300 chars | ملاحظة نصية اختيارية تصف الصورة، تُستخدم لتوجيه خطوة التحليل التجريبية. |
| params.colorize | boolean | نعم | — | مطلوب للتوافق مع المخطط. تُقبل القيمة لكنها لا تحدّد وضع معالجة؛ فمسار الترميم واحد مهما كانت القيمة. |
| params.resolution | unknown | نعم | — | |
| params.variant | unknown | نعم | — |
نص الاستجابة
| الاسم | النوع | مطلوب | الحدود | الوصف |
|---|---|---|---|---|
| job_id | string | نعم | job_<uuid> | المعرّف الفريد لهذه المهمة. |
| status | pending | processing | succeeded | failed | cancelled | نعم | — | الحالة الحالية لدورة حياة المهمة. |
مثال استجابة 202
{
"job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "pending"
}أمثلة الكود
curl -X POST 'https://your-app.example.com/api/restore' \
-H 'Content-Type: application/json' \
-d '{ "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "user_hint": "the sky was blue", "params": { "colorize": true }}'/api/upscaleإنشاء مهمة تكبير
يبدأ مهمة تكبير غير متزامنة لصورة تم رفعها مسبقًا، بالوضع والدقة المستهدفة المطلوبين. يعيد فورًا مرجع مهمة بحالة pending.
نص الطلب
| الاسم | النوع | مطلوب | الحدود | الوصف |
|---|---|---|---|---|
| image_url | string | نعم | /api/mock-assets/<uuid> | عنوان URL لأصل من نفس المصدر يُعاد من عملية رفع سابقة — الشكل الوحيد المقبول لـ image_url. |
| user_hint | string | لا | max 300 chars | ملاحظة نصية اختيارية تصف الصورة، تُستخدم لتوجيه خطوة التحليل التجريبية. |
| params.mode | fast | balanced | high | نعم | — | المفاضلة بين الجودة والسرعة عند التكبير. |
| params.target_megapixels | number | نعم | 1–64 | دقة الإخراج المطلوبة، بالميجابكسل. |
نص الاستجابة
| الاسم | النوع | مطلوب | الحدود | الوصف |
|---|---|---|---|---|
| job_id | string | نعم | job_<uuid> | المعرّف الفريد لهذه المهمة. |
| status | pending | processing | succeeded | failed | cancelled | نعم | — | الحالة الحالية لدورة حياة المهمة. |
مثال استجابة 202
{
"job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "pending"
}أمثلة الكود
curl -X POST 'https://your-app.example.com/api/upscale' \
-H 'Content-Type: application/json' \
-d '{ "image_url": "/api/mock-assets/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "params": { "mode": "fast", "target_megapixels": 12 }}'/api/jobs/{job_id}الحصول على حالة المهمة
يعيد الحالة الحالية للمهمة: status وprogress، وبمجرد أن تصبح succeeded، عنوان result_url يمكنك تنزيله أو إعادة إرساله كـ image_url جديد.
نص الاستجابة
| الاسم | النوع | مطلوب | الحدود | الوصف |
|---|---|---|---|---|
| job_id | string | نعم | job_<uuid> | المعرّف الفريد لهذه المهمة. |
| type | restore | upscale | نعم | — | الأداة التي أنشأت هذه المهمة. |
| status | pending | processing | succeeded | failed | cancelled | نعم | — | الحالة الحالية لدورة حياة المهمة. |
| progress | number | نعم | 0–100 | النسبة المئوية للإنجاز، من 0 إلى 100. |
| result_url | string | لا | — | يظهر بمجرد نجاح المهمة — عنوان URL لأصل من نفس المصدر يمكن أيضًا إرساله كـ image_url جديد. |
| result_urls.light | string | نعم | — | |
| result_urls.strong | string | لا | — | |
| before_url | string | لا | — | |
| error.code | INVALID_REQUEST | UNSUPPORTED_FORMAT | FILE_TOO_LARGE | JOB_NOT_FOUND | VLM_FAILED | WORKFLOW_FAILED | TIMEOUT | CANCELLED | INTERNAL | INSUFFICIENT_CREDITS | STORAGE_QUOTA_EXCEEDED | نعم | — | سبب الفشل القابل للقراءة آليًا. |
| error.message | string | نعم | — | رسالة فشل قابلة للقراءة البشرية. تظهر فقط عندما تكون status هي failed. |
| created_at | string | نعم | — | وقت إنشاء المهمة، بصيغة ISO 8601. |
| updated_at | string | نعم | — | وقت آخر تحديث للمهمة، بصيغة ISO 8601. |
مثال استجابة 200
{
"job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "restore",
"status": "succeeded",
"progress": 100,
"result_url": "/api/mock-assets/6c1d3a2e-4f5b-4a1e-9c2d-1a2b3c4d5e6f",
"created_at": "2026-08-03T10:15:00.000Z",
"updated_at": "2026-08-03T10:15:42.000Z"
}أمثلة الكود
curl -X GET 'https://your-app.example.com/api/jobs/job_3fa85f64-5717-4562-b3fc-2c963f66afa6'/api/jobs/{job_id}/cancelإلغاء مهمة
يطلب إلغاء مهمة. إلغاء مهمة وصلت بالفعل إلى حالة نهائية لا يُحدث أي أثر ويعيد حالتها الحالية دون تغيير.
نص الاستجابة
| الاسم | النوع | مطلوب | الحدود | الوصف |
|---|---|---|---|---|
| job_id | string | نعم | job_<uuid> | المعرّف الفريد لهذه المهمة. |
| status | pending | processing | succeeded | failed | cancelled | نعم | — | الحالة الحالية لدورة حياة المهمة. |
مثال استجابة 202
{
"job_id": "job_3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "cancelled"
}أمثلة الكود
curl -X POST 'https://your-app.example.com/api/jobs/job_3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel'دورة حياة حالة المهمة
تمر كل مهمة بآلة الحالات هذه. الحالتان pending وprocessing غير نهائيتين؛ أما succeeded وfailed وcancelled فهي حالات نهائية ولا تتغير بعدها أبدًا.
إذا لم تصل المهمة إلى حالة نهائية ضمن مهلة الاستطلاع لدى العميل، تُعامل كفشل من نوع TIMEOUT.
رموز الأخطاء
تستخدم جميع الأخطاء مجموعة الرموز الثابتة هذه. تُعاد الرموز INVALID_REQUEST وUNSUPPORTED_FORMAT وFILE_TOO_LARGE وJOB_NOT_FOUND كاستجابات خطأ HTTP؛ أما الباقي فيظهر كـ error.code داخل كائن المهمة عندما تصل تلك المهمة إلى حالة نهائية failed أو cancelled.
| الرمز | أين يظهر | المعنى |
|---|---|---|
| INVALID_REQUEST | استجابة خطأ HTTP 400 | هذا الطلب غير صالح. يرجى التحقق من البيانات المدخلة والمحاولة مرة أخرى. |
| UNSUPPORTED_FORMAT | استجابة خطأ HTTP 415 | صيغة الملف هذه غير مدعومة. يرجى استخدام JPEG أو PNG أو WebP أو HEIC أو HEIF. |
| FILE_TOO_LARGE | استجابة خطأ HTTP 413 | هذا الملف كبير جدًا. يرجى استخدام صورة أصغر. |
| JOB_NOT_FOUND | استجابة خطأ HTTP 404 | لم نتمكن من العثور على هذه المهمة. ربما تكون قد انتهت صلاحيتها. |
| VLM_FAILED | داخل حقل error لمهمة وصلت إلى حالة نهائية | لم نتمكن من تحليل هذه الصورة. يرجى المحاولة مرة أخرى. |
| WORKFLOW_FAILED | داخل حقل error لمهمة وصلت إلى حالة نهائية | فشلت المعالجة. يرجى المحاولة مرة أخرى. |
| TIMEOUT | داخل حقل error لمهمة وصلت إلى حالة نهائية | تستغرق هذه العملية وقتًا أطول من المتوقع. يرجى المحاولة مرة أخرى. |
| CANCELLED | داخل حقل error لمهمة وصلت إلى حالة نهائية | تم إلغاء هذه المهمة. |
| INTERNAL | استجابة خطأ HTTP 500 | حدث خطأ من جانبنا. يرجى المحاولة مرة أخرى. |
| INSUFFICIENT_CREDITS | استجابة خطأ HTTP 402 | لا يوجد لديك رصيد كافٍ لهذه المهمة. أعد الشحن للمتابعة. |
| STORAGE_QUOTA_EXCEEDED | استجابة خطأ HTTP 413 | ألبومك ممتلئ. احذف بعض الصور أو قم بالترقية للمتابعة. |
من المخطط توفير بوابة /v1 ذات إصدار للتكاملات مع أطراف ثالثة — مفاتيح واجهة برمجة تطبيقات بدلًا من ملفات تعريف ارتباط الجلسة، وwebhooks عند اكتمال المهمة بدلًا من الاستطلاع المتكرر، وحدود لمعدل الطلبات لكل مفتاح. لم يُنفَّذ أي من ذلك بعد، ولم يُلتزم بأي شكل لطلب أو استجابة، أو آلية مصادقة، أو توقيع webhook، أو رقم لحد المعدل. اعتبر كل ما هو أعلى هذا القسم — مسارات /api من نفس المصدر التي يقدمها هذا التطبيق فعليًا — العقد الوحيد الساري اليوم. إذا تم إطلاق /v1، فسيُوثَّق بشكل منفصل مع مواصفات كاملة؛ هذه الفقرة مجرد إشعار مسبق، وليست معاينة.