أمثلة API

الإصدار

API

المسار

POST PUT POST

/api/v2/api/translate/uploads
R2 target
/api/v2/api/translate

المعاملات

المعامل	مطلوب	النوع	الوصف
`image`	نعم	file[]	ملف صورة واحد أو أكثر، أو ملف ZIP
`source_language`	لا	string	اختياري؛ مطلوب عند اختيار نموذج manga (مثال: ja)
`target_language`	نعم	string	رمز لغة الهدف (مثال: en)
`model`	لا	string	نموذج التعرف؛ اتركه فارغًا لاستخدام الإعداد الافتراضي للواجهة
`font`	لا	string	نمط الخط؛ اتركه فارغًا لاستخدام الإعداد الافتراضي للواجهة

المعامل	مطلوب	النوع	الوصف
`Idempotency-Key`	نعم	HTTP header	ترويسة طلب التحضير: مفتاح ثابت لإعادة محاولة نفس قائمة الملفات بأمان خلال 8 ساعات
`platform`	لا	string \| null	طلبا التحضير والإرسال النهائي: تسمية منصة اختيارية يصرح بها العميل وتستخدم فقط لتدقيق استدعاءات API
`files[]`	نعم	array<object>	طلب التحضير: بيانات وصفية للملف تتضمن filename وcontent_type وsize وcontent_sha256
`upload_id`	نعم	string	طلب الإرسال النهائي: معرّف دفعة التحميل المعتم الذي أعاده طلب التحضير
`files[].index files[].upload_intent`	نعم	integer string	طلب الإرسال النهائي: index لكل ملف وupload_intent المعتم اللذان أعادهما طلب التحضير؛ أرسلهما فقط بعد اكتمال تحميل كل ملف إلى R2
`source_language`	لا	string	اختياري؛ مطلوب عند اختيار نموذج manga (مثال: ja)
`target_language`	نعم	string	رمز لغة الهدف (مثال: en)
`model`	لا	string	نموذج التعرف؛ اتركه فارغًا لاستخدام الإعداد الافتراضي للواجهة
`font`	لا	string	نمط الخط؛ اتركه فارغًا لاستخدام الإعداد الافتراضي للواجهة

المعامل	مطلوب	النوع	الوصف
`batch_id`	نعم	string	معرف الدفعة المستخدم للاستعلام عن حالة المهمة

المعامل	مطلوب	النوع	الوصف
لا توجد معاملات

معلمات الاستجابة

الحقل	النوع	الوصف
`task_id`	string	معرف المهمة
`batch_id`	string	معرف الدفعة المستخدم للاستعلام عن حالة المهمة

الحقل	النوع	الوصف
`status`	integer	رمز حالة التطبيق؛ 200 عند النجاح
`cost_ms`	integer	الوقت المستغرق لمعالجة طلب API هذا بالمللي ثانية
`request_id`	string	معرف الطلب لتتبع استدعاء API هذا
`data`	object	معرفات مهمة الترجمة المعادة بعد قبول الطلب
`message`	string	تكون دائمًا success عند نجاح استجابة API؛ ولا تعني اكتمال مهمة الترجمة
`data.task_id`	string	معرف المهمة
`data.batch_id`	string	معرف الدفعة المستخدم للاستعلام عن حالة المهمة

الحقل	النوع	الوصف
`status_code`	integer	القيمة دائمًا 200 لاستجابة Task Status ناجحة
`request_id`	string	معرف الطلب لتتبع استدعاء API هذا
`auth_type`	string	القيمة دائمًا account لطلب Task Status مصادق عليه باستخدام PAT
`task_reference`	string	قيمة batch_id من مسار الطلب، وتُعاد دون تغيير
`data`	object	حاوية لنتائج كل صورة والحالة الإجمالية للمهمة
`data.items`	array<object>	مصفوفة نتائج المهمة لكل صورة
`data.items[].image_id`	string	معرف ثابت لنتيجة الصورة
`data.items[].index`	integer	موضع الصورة في الدفعة ابتداءً من الصفر
`data.items[].filename`	string	اسم ملف الصورة الأصلي
`data.items[].status`	string	حالة نتيجة الصورة (pending \| processing \| completed \| failed \| canceled)
`data.items[].original_url`	string	عنوان URL للصورة المصدر، وهو متاح للمهام الحالية المنشأة عبر API.
`data.items[].translated_url`	string	عنوان URL للصورة المترجمة؛ يكون سلسلة فارغة حتى تتوفر النتيجة، بما في ذلك الصور المعلقة أو قيد المعالجة أو الفاشلة.
`data.items[].is_translated`	boolean	تكون true فقط عند توفر عنوان URL لصورة مترجمة مكتملة
`data.items[].output_file_path`	string	اسم متوافق مع translated_url؛ يكون سلسلة فارغة عند عدم توفر صورة مترجمة.
`data.items[].message`	string \| null	رسالة معلومات اختيارية
`data.items[].error`	string \| null	تفاصيل الخطأ عند فشل مهمة الصورة؛ وإلا تكون null
`data.items[].inpaint_image_url`	string \| null	عنوان URL لصورة إزالة النص، أو null إذا كان النموذج أو مسار التنفيذ المحدد لا ينشئها.
`data.items[].block_json`	array<object>	كتل نص منظمة يحتفظ بها V1؛ قد تكون مصفوفة فارغة إذا لم يُرجع النموذج أو المسار بيانات الكتل.
`data.task_status`	string	الحالة الإجمالية للمهمة (pending \| processing \| completed \| failed \| canceled)

الحقل	النوع	الوصف
`status`	integer	رمز حالة التطبيق؛ 200 عند النجاح
`cost_ms`	integer	الوقت المنقضي للمهمة بالمللي ثانية؛ يكون 0 عند غياب طوابع زمنية صالحة
`request_id`	string	معرف الطلب لتتبع استدعاء API هذا
`data`	array<object>	مصفوفة موجزة لنتائج كل صورة
`message`	string	تكون دائمًا success عند نجاح استجابة API؛ ولا تعني اكتمال مهمة الترجمة
`data[].image_id`	string	معرف ثابت لنتيجة الصورة
`data[].filename`	string	اسم ملف الصورة الأصلي
`data[].status`	string	حالة نتيجة الصورة (pending \| processing \| completed \| failed \| canceled)
`data[].original_url`	string	عنوان URL للصورة المصدر، وهو متاح للمهام الحالية المنشأة عبر API.
`data[].translated_url`	string	عنوان URL للصورة المترجمة؛ يكون سلسلة فارغة حتى تتوفر النتيجة، بما في ذلك الصور المعلقة أو قيد المعالجة أو الفاشلة.
`data[].erased_url`	string	عنوان URL لصورة إزالة النص؛ قد يكون سلسلة فارغة. النماذج أو المسارات التي تعيد الصورة النهائية فقط، مثل Manga مع مسار الصورة النهائية Auto، لا تنشئها.
`data[].blocks`	array<object>	كتل نص مترجم منظمة؛ قد تكون مصفوفة فارغة إذا لم يُرجع النموذج أو المسار بيانات الكتل، مثل Manga مع مسار الصورة النهائية Auto.
`data[].blocks[].angle`	number	زاوية دوران كتلة النص
`data[].blocks[].color`	string	اللون السداسي المستخدم للنص المترجم
`data[].blocks[].handwritten`	boolean	ما إذا تم اكتشاف النص المصدر على أنه مكتوب بخط اليد
`data[].blocks[].location`	object	حدود الزوايا الأربع لكتلة النص
`data[].blocks[].location.left_bottom`	array<number>	زوج إحداثيات الزاوية المحددة
`data[].blocks[].location.right_bottom`	array<number>	زوج إحداثيات الزاوية المحددة
`data[].blocks[].location.left_top`	array<number>	زوج إحداثيات الزاوية المحددة
`data[].blocks[].location.right_top`	array<number>	زوج إحداثيات الزاوية المحددة
`data[].blocks[].text`	string	النص المترجم المعروض في الكتلة
`data[].blocks[].direction`	string	اتجاه كتابة النص المترجم

الحقل	النوع	الوصف
`subscription_credits`	integer	رصيد النقاط للفئة المحددة
`subscription_credits_expires_at`	string \| null	وقت انتهاء رصيد الاشتراك بتنسيق ISO 8601، أو null
`one_time_credits`	integer	رصيد النقاط للفئة المحددة
`one_time_credits_expires_at`	string \| null	وقت انتهاء الرصيد لمرة واحدة بتنسيق ISO 8601، أو null
`free_credits`	integer	رصيد النقاط للفئة المحددة
`total_credits`	integer	مجموع كل أرصدة النقاط المتاحة
`is_temporary`	boolean	ما إذا كان الرصيد يخص حسابًا مؤقتًا

الحقل	النوع	الوصف
`status`	integer	رمز حالة التطبيق؛ 200 عند النجاح
`cost_ms`	integer	الوقت المستغرق لمعالجة طلب API هذا بالمللي ثانية
`request_id`	string	معرف الطلب لتتبع استدعاء API هذا
`data`	object	حاوية أرصدة النقاط الحالية
`message`	string	تكون دائمًا success عند نجاح استجابة API؛ ولا تعني اكتمال مهمة الترجمة
`data.total_credits`	integer	مجموع كل أرصدة النقاط المتاحة
`data.is_temporary`	boolean	ما إذا كان الرصيد يخص حسابًا مؤقتًا
`data.detail`	object	تفصيل الأرصدة المتاحة حسب الفئة
`data.detail.subscription`	object	رصيد النقاط ووقت انتهائه للفئة المحددة
`data.detail.subscription.credits`	integer	رصيد النقاط للفئة المحددة
`data.detail.subscription.expires_at`	string \| null	وقت انتهاء الرصيد بتنسيق ISO 8601، أو null
`data.detail.one_time`	object	رصيد النقاط ووقت انتهائه للفئة المحددة
`data.detail.one_time.credits`	integer	رصيد النقاط للفئة المحددة
`data.detail.one_time.expires_at`	string \| null	وقت انتهاء الرصيد بتنسيق ISO 8601، أو null
`data.detail.free`	object	رصيد النقاط ووقت انتهائه للفئة المحددة
`data.detail.free.credits`	integer	رصيد النقاط للفئة المحددة
`data.detail.free.expires_at`	null	دائمًا null لأن واجهة التجميع هذه لا توفر وقت انتهاء موحدًا للنقاط المجانية

استجابة نموذجية (JSON)

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "batch_id": "00000000-0000-4000-8000-000000000001"
}

استجابة نموذجية (JSON)

{
  "status": 200,
  "cost_ms": 125,
  "request_id": "4b7370383cacccc7",
  "data": {
    "task_id": "00000000-0000-4000-8000-000000000001",
    "batch_id": "00000000-0000-4000-8000-000000000001"
  },
  "message": "success"
}

استجابة نموذجية (JSON)

{
  "status_code": 200,
  "request_id": "4b7370383cacccc7",
  "auth_type": "account",
  "task_reference": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "image_id": "00000000-0000-4000-8000-000000000001_0",
        "index": 0,
        "filename": "007.jpg",
        "status": "completed",
        "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
        "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "is_translated": true,
        "output_file_path": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "message": "ok",
        "error": null,
        "inpaint_image_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
        "block_json": []
      }
    ],
    "task_status": "completed"
  }
}

استجابة نموذجية (JSON)

{
  "status": 200,
  "cost_ms": 5300,
  "request_id": "4b7370383cacccc7",
  "data": [
    {
      "image_id": "00000000-0000-4000-8000-000000000001_0",
      "filename": "007.jpg",
      "status": "completed",
      "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
      "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
      "erased_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
      "blocks": [
        {
          "angle": 0,
          "color": "#484848",
          "handwritten": false,
          "location": {
            "left_bottom": [1685, 293],
            "right_bottom": [1786, 293],
            "left_top": [1685, 264],
            "right_top": [1786, 264]
          },
          "text": "OOOUGH!",
          "direction": "horizontal"
        }
      ]
    }
  ],
  "message": "success"
}

استجابة نموذجية (JSON)

{
  "subscription_credits": 0,
  "subscription_credits_expires_at": null,
  "one_time_credits": 0,
  "one_time_credits_expires_at": null,
  "free_credits": 10,
  "total_credits": 10,
  "is_temporary": true
}

استجابة نموذجية (JSON)

{
  "status": 200,
  "cost_ms": 4,
  "request_id": "4b7370383cacccc7",
  "data": {
    "total_credits": 10,
    "is_temporary": true,
    "detail": {
      "subscription": {
        "credits": 0,
        "expires_at": null
      },
      "one_time": {
        "credits": 0,
        "expires_at": null
      },
      "free": {
        "credits": 10,
        "expires_at": null
      }
    }
  },
  "message": "success"
}

معلمات استجابة الخطأ

عند حدوث فشل في V2، تُحافَظ على حالة HTTP ويُعاد غلاف الاستجابة نفسه المكوّن من خمسة حقول.

الحقل	النوع	الوصف
`status`	integer	رمز حالة خطأ HTTP الفعلي
`cost_ms`	integer	الوقت المستغرق لمعالجة طلب API هذا بالمللي ثانية
`request_id`	string	معرف الطلب لتتبع استدعاء API هذا
`data`	object	حاوية بيانات خطأ فارغة باستثناء الرمز الثابت القابل للقراءة آليًا
`message`	string	رسالة خطأ عامة؛ لا تُكشف تفاصيل التشخيص الداخلية
`data.code`	string	رمز خطأ ثابت قابل للقراءة آليًا

مثال على استجابة الخطأ (JSON)

{
  "status": 400,
  "cost_ms": 1,
  "request_id": "4b7370383cacccc7",
  "data": {
    "code": "PZ_API_ACCESS_BAD_REQUEST"
  },
  "message": "Invalid target language"
}

مدخلات المثال

مفتاح API

لغة المصدر

لغة الهدف

النموذج

الخط

أمثلة API

المسار

المعاملات

معلمات الاستجابة

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

معلمات استجابة الخطأ

مثال على استجابة الخطأ (JSON)

مدخلات المثال

مثال Python3

أمثلة cURL

مثال Python3

cURL

مثال Python3

cURL

المسار

المعاملات

معلمات الاستجابة

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

استجابة نموذجية (JSON)

معلمات استجابة الخطأ

مثال على استجابة الخطأ (JSON)

مدخلات المثال

مثال Python3

أمثلة cURL

مثال Python3

cURL

مثال Python3

cURL

تفضيلات ملفات تعريف الارتباط