مرجع Python API

تواقيع subft-client ومعاملاته وعقود إرجاعه وصادراته العامة.

المعاملات والقيم المعادة والأخطاء

هذا عميل HTTP متزامن ومحدود الوظيفة. لا يطلب إدخالاً ولا يفحص الملفات تلقائياً ولا ينسّق العمل المدفوع نيابةً عنك. ابدأ بـالمثال الكامل. تحتاج دوال API إلى حساب ورمز وإذن للمشروع المختار. لا تخصم الخطة والتقدير رصيداً؛ اعتماد العملية يفعل ذلك. يتطلب توليد الرمز أو إلغاؤه الحساب الموثّق ويستبدل رمزه النشط الوحيد أو يلغيه.

تصف أنواع positional-only وpositional-or-keyword وkeyword-only والأنواع المتغيرة صيغة الاستدعاء في Python. تعني الشرطة في عمود الافتراض عدم وجود قيمة افتراضية؛ يجب توفير المعاملات المطلوبة. تعني _UNSET حذف الحقل، بينما قد تمسح None حقل مشروع يقبل الفراغ صراحةً.

JsonValue هو Any وليس نموذج استجابة متحققاً منه. تعيد أدوات HTTP بيانات JSON مفكوكة أو None للاستجابة الفارغة؛ راجع مخططات الاستجابة أدناه للحقول الموثقة. تعيد request وput_upload_target كائناً من httpx.Response، وتعيد close القيمة None، وتعيد resolve_url نص عنوان.

التقط SubftMaintenanceError قبل SubftApiError؛ افحص status_code وpayload وresponse وmode وmaintenance_until. يحتفظ SubftTransportError بـrequest_error. يغطي SubftError أخطاء العميل؛ وقد يرفع التحقق من المعاملات ValueError أيضاً. تتطلب 409 قراءة أو خطة جديدة، وليس تكرار قيم تحقق قديمة. احتفظ بالرسائل التقنية في السجلات الداخلية وحوّل الرموز إلى نص مترجم في الواجهات العامة. لا تكرر اعتماداً مدفوعاً دون تحقق بعد فشل نقل ملتبس: طابق العملية المقبولة أولاً.

تستخدم أخطاء HTTP البنية {"detail":{"code":"…","params":{…}}}. اقرأ SubftApiError.code وSubftApiError.params؛ نصوص الخادم الخام مخصصة للتشخيص فقط. تتضمن المعاملات مبالغ الرصيد وبيانات الصيانة وأرقام أسطر الترجمة النصية. مثلاً، قد تعيد الترجمة غير القابلة للقراءة {"detail":{"code":"invalid_subtitles","params":{"line":2}}}. يجب أن تعرض الواجهات العامة رسالة عامة مترجمة للرموز غير المعروفة.

SubftClient

أنشئ عميلاً واحداً وأغلقه بمدير السياق. تُستورد الإضافات صراحةً؛ لا تحمّل الحزمة الأساسية تبعيات FFmpeg أو WebSocket.

Python

SubftClient(
    base_url: str,
    *,
    token: str | None = None,
    timeout: float | httpx.Timeout = 30.0,
    headers: Mapping[str, str] | None = None,
    cookies: Mapping[str, str] | None = None,
    transport: httpx.BaseTransport | None = None
) -> None

المعامل	النوع	التمرير	الافتراض	المعنى
`base_url`	`str`	`positional-or-keyword`	—	عنوان البوابة التي تقدم مسارات API والمصادقة والاتصال الفوري؛ تُوحّد الشرطة المائلة الأخيرة.
`token`	`str \| None`	`keyword-only`	`None`	رمز API من صفحة وصول المطورين. احفظه في متغير بيئة محمي.
`timeout`	`float \| httpx.Timeout`	`keyword-only`	`30.0`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.
`headers`	`Mapping[str, str] \| None`	`keyword-only`	`None`	ترويسات HTTP. مرّر ترويسات هدف الرفع دون تغيير؛ ترويسات الطلب العادي تتجاوز ترويسات المنشئ.
`cookies`	`Mapping[str, str] \| None`	`keyword-only`	`None`	ملفات ارتباط HTTP اختيارية لجلسة هذا العميل.
`transport`	`httpx.BaseTransport \| None`	`keyword-only`	`None`	وسيلة نقل HTTPX اختيارية؛ استخدم MockTransport في الاختبارات بدلاً من بوابة حية.

دوال العميل

ترد كل دالة عامة مرة واحدة أدناه. تتبع القيم المعادة والأخطاء المشتركة العقد أعلاه؛ تحتفظ تعارضات نقطة النهاية بحالة الخادم وبياناته.

`abandon_content_preparation`

التخلي عن تحضير مصدر واحد ما زال قابلاً للإجراء، مع الحفاظ على مصادر العملية الأخرى.

Python

abandon_content_preparation(
    operation_id: str, media_id: str, content_id: str
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`content_id`	`str`	`positional-or-keyword`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.

`abort_operation`

إيقاف العمل الذي قبله الخادم باستخدام الإجراء المسموح للعملية؛ يختلف ذلك عن فصل المراقبة.

Python

abort_operation(operation_id: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.

`add_project_media`

تسجيل عنصر جرد واحد تم فحصه محلياً مع مصادره الفعلية.

Python

add_project_media(
    project_id: str, media: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media`	`Mapping[str, Any]`	`positional-or-keyword`	—	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.

`add_project_media_bulk`

تسجيل دفعة كاملة من سجلات الوسائط المفحوصة.

Python

add_project_media_bulk(
    project_id: str, media: Iterable[Mapping[str, Any]]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media`	`Iterable[Mapping[str, Any]]`	`positional-or-keyword`	—	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.

`apply_project_directory_sync`

تطبيق لقطة مجلد تمت مراجعتها مع قيم تحقق حديثة؛ تتطلب الحالة القديمة معاينة جديدة.

Python

apply_project_directory_sync(
    project_id: str,
    *,
    files: Iterable[Mapping[str, Any]],
    media: Iterable[Mapping[str, Any]] | None = None,
    confirmed_moves: Iterable[Mapping[str, Any]] | None = None,
    confirm_reviewed: bool = False,
    expected_assets: Mapping[str, Any] | None = None,
    complete: bool = True
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`files`	`Iterable[Mapping[str, Any]]`	`keyword-only`	—	لقطة مجلد كاملة أو قائمة ملفات أو أدلة ملاحظة تتطلبها نقطة النهاية؛ أنشئها من الملفات المحلية.
`media`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.
`confirmed_moves`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	خرائط مسارات الوسائط القديمة والجديدة التي تمت مراجعتها من معاينة المجلد.
`confirm_reviewed`	`bool`	`keyword-only`	`False`	موافقة صريحة على تغييرات المجلد التي تمت مراجعتها؛ لا يضيف العميل موافقة ضمنية.
`expected_assets`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	قيم التحقق الحالية للملاحظة أو الجيل أو الحفظ من استجابة القراءة أو بدء الفحص؛ تتطلب القيم القديمة قراءة جديدة.
`complete`	`bool`	`keyword-only`	`True`	يحدد ما إذا كانت اللقطة كاملة؛ لا تصف فحصاً محلياً فشل جزئياً بأنه كامل.

`archive_project`

أرشفة مشروع اكتملت تسوية مهامه ليصبح للقراءة فقط. تكرار الطلب يحافظ على تاريخ الأرشفة.

Python

archive_project(project_id: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.

`restore_project`

استعادة مشروع مؤرشف لإتاحة تعديله مجددًا. لا تؤدي استعادة مشروع نشط إلى أي تغيير.

Python

restore_project(project_id: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.

`delete_project`

حذف مشروع مؤرشف نهائيًا مع مساحة العمل والنتائج والمدخلات المقدمة. تبقى سجلات المهام والرصيد. يجب أن يطابق اسم التأكيد اسم المشروع تمامًا بعد إزالة المسافات المحيطة، مع مراعاة حالة الأحرف.

Python

delete_project(project_id: str, confirmation_name: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`confirmation_name`	`str`	`positional-or-keyword`	—	اسم المشروع مطابقًا تمامًا بعد إزالة المسافات المحيطة، مع مراعاة حالة الأحرف.

`attach_project_media_sidecars`

إرفاق ملفات ترجمة جانبية تمت مراجعتها بعنصر وسائط باستخدام خط أساس الفحص.

Python

attach_project_media_sidecars(
    project_id: str,
    media_id: str,
    sidecars: Iterable[Mapping[str, Any]],
    *,
    expected_assets: Iterable[Mapping[str, Any]] = ()
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`sidecars`	`Iterable[Mapping[str, Any]]`	`positional-or-keyword`	—	ملفات ترجمة جانبية تم فحصها مع بيانات الاقتران والتصنيف.
`expected_assets`	`Iterable[Mapping[str, Any]]`	`keyword-only`	`()`	قيم التحقق الحالية للملاحظة أو الجيل أو الحفظ من استجابة القراءة أو بدء الفحص؛ تتطلب القيم القديمة قراءة جديدة.

`begin_media_asset_checks`

قراءة خط أساس فحص الأصول الحالي قبل مطابقة الملاحظات الفعلية.

Python

begin_media_asset_checks(
    project_id: str, media_id: str, *, scope: Mapping[str, Any] | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`scope`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	محدد خاص بنقطة النهاية لنوع الأصل أو نطاق الفحص أو الجاهزية أو الموضع؛ اتبع عقد نقطة النهاية.

`begin_project_directory_checks`

قراءة خطوط أساس فحص الأصول لدورة كاملة من معاينة المجلد وتطبيقها.

Python

begin_project_directory_checks(project_id: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.

`clone_media_asset`

إنشاء نسخة قابلة للتحرير أو نسخة مكررة باستخدام قيم التحقق للّقطة الحالية.

Python

clone_media_asset(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`positional-or-keyword`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`close`

إغلاق مجموعة اتصالات HTTP؛ يستدعي مدير السياق ذلك تلقائياً.

Python

close() -> None

`compare_media_asset_exports`

مقارنة مرشحات التصدير المختارة دون استخراج ملفات محلية أو كتابتها.

Python

compare_media_asset_exports(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`positional-or-keyword`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`complete_media_asset_checks`

إكمال الفحوص الفعلية المحمية ومطابقة المصادر التي تمت ملاحظتها حديثاً.

Python

complete_media_asset_checks(
    project_id: str, media_id: str, payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`complete_upload`

إتمام الرفع المباشر لعنصر المصدر والرفع ومحاولة التحضير الحالية.

Python

complete_upload(
    operation_id: str,
    media_id: str,
    *,
    content_id: str,
    attempt_id: str,
    upload_id: str,
    content_hash: str | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`content_id`	`str`	`keyword-only`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`attempt_id`	`str`	`keyword-only`	—	قيمة UUID جديدة يختارها المستدعي وتؤكدها استجابة التحضير؛ استخدمها في كل طلب يخص هذه المحاولة.
`upload_id`	`str`	`keyword-only`	—	معرّف الرفع من استجابة الهدف الحالية، المرتبط بالمحاولة الحالية.
`content_hash`	`str \| None`	`keyword-only`	`None`	تجزئة البايتات المحضّرة أو تجزئة زوج الملفات الموثقة، وليست بصمة الوسائط الأصلية.

`create_blank_media_asset`

إنشاء أصل ترجمة نصية فارغ قابل للتحرير باستخدام طلب نقطة النهاية المحمي.

Python

create_blank_media_asset(
    project_id: str, media_id: str, payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`create_project`

إنشاء مشروع ملف أو مجلد فارغ؛ يُرسل الجرد المحلي بشكل منفصل.

Python

create_project(
    *, name: str, mode: str, root_label: str | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`name`	`str`	`keyword-only`	—	اسم عرض المشروع؛ يمكن أن يستخدم update_project القيمة None لمسح قيمة تقبل الفراغ.
`mode`	`str`	`keyword-only`	—	وضع المشروع: file أو directory.
`root_label`	`str \| None`	`keyword-only`	`None`	تسمية مقروءة للمجلد أو الملف الجذر، وليست مساراً محلياً يمكن للخادم الوصول إليه.

`create_project_operation`

اعتماد اختيارات المصادر المحمية والمقدّرة وخصم التقدير المقبول.

Python

create_project_operation(
    project_id: str,
    *,
    media_ids: Iterable[str],
    target_language: str,
    content_overrides: Iterable[Mapping[str, Any]] | None = None,
    metrics: Iterable[Mapping[str, Any]] | None = None,
    source_selections: Iterable[Mapping[str, Any]]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_ids`	`Iterable[str]`	`keyword-only`	—	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.
`target_language`	`str`	`keyword-only`	—	رمز اللغة الهدف للترجمة النصية المولدة أو المترجمة.
`content_overrides`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	تجاوزات مرتبطة بمرجع source_ref ثابت: تفعيل المصدر أو تحديد لغته صراحةً.
`metrics`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	مقاييس المصدر التي تطلبها الخطة الحالية فقط، محسوبة محلياً. مدة الصوت موجودة بالفعل في الجرد المفحوص.
`source_selections`	`Iterable[Mapping[str, Any]]`	`keyword-only`	—	اختيارات محمية من الخطة المقدّرة مع source_language الموحّدة؛ احتفظ باللقطات والملاحظات.

`create_project_operation_plan`

طلب خطة للمصادر والمراحل دون خصم رصيد أو رفع بيانات.

Python

create_project_operation_plan(
    project_id: str,
    *,
    media_ids: Iterable[str],
    target_language: str,
    content_overrides: Iterable[Mapping[str, Any]] | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_ids`	`Iterable[str]`	`keyword-only`	—	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.
`target_language`	`str`	`keyword-only`	—	رمز اللغة الهدف للترجمة النصية المولدة أو المترجمة.
`content_overrides`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	تجاوزات مرتبطة بمرجع source_ref ثابت: تفعيل المصدر أو تحديد لغته صراحةً.

`create_upload_target`

طلب هدف رفع مباشر أو تحديثه بعد دخول التحضير في حالة التجزئة أو الرفع.

Python

create_upload_target(
    operation_id: str,
    media_id: str,
    *,
    content_id: str,
    attempt_id: str,
    content_hash: str,
    filename: str | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`content_id`	`str`	`keyword-only`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`attempt_id`	`str`	`keyword-only`	—	قيمة UUID جديدة يختارها المستدعي وتؤكدها استجابة التحضير؛ استخدمها في كل طلب يخص هذه المحاولة.
`content_hash`	`str`	`keyword-only`	—	تجزئة البايتات المحضّرة أو تجزئة زوج الملفات الموثقة، وليست بصمة الوسائط الأصلية.
`filename`	`str \| None`	`keyword-only`	`None`	اسم الملف المحضّر مع امتداده الفعلي، لتحديد تنسيق التخزين.

`estimate_project_operation_plan`

تقدير الخطة الحالية باستخدام المقاييس الفعلية المطلوبة؛ افحص can_commit قبل طلب الموافقة.

Python

estimate_project_operation_plan(
    project_id: str,
    *,
    media_ids: Iterable[str],
    target_language: str,
    content_overrides: Iterable[Mapping[str, Any]] | None = None,
    metrics: Iterable[Mapping[str, Any]] | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_ids`	`Iterable[str]`	`keyword-only`	—	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.
`target_language`	`str`	`keyword-only`	—	رمز اللغة الهدف للترجمة النصية المولدة أو المترجمة.
`content_overrides`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	تجاوزات مرتبطة بمرجع source_ref ثابت: تفعيل المصدر أو تحديد لغته صراحةً.
`metrics`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	مقاييس المصدر التي تطلبها الخطة الحالية فقط، محسوبة محلياً. مدة الصوت موجودة بالفعل في الجرد المفحوص.

`export_media_asset`

التقاط تصدير ترجمة لأصل محفوظ مع قيم تحقق حديثة للّقطة والإصدار والبيانات الوصفية.

Python

export_media_asset(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`positional-or-keyword`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`export_project_operation_artifact`

تصدير مرحلة ناجحة وثابتة محددة؛ لا يُنشئ التنزيل أصلاً قابلاً للتحرير أو أصلاً فعلياً.

Python

export_project_operation_artifact(
    project_id: str,
    operation_id: str,
    artifact_id: str,
    *,
    output_target: str | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`artifact_id`	`str`	`positional-or-keyword`	—	معرّف ناتج مرحلة ناجحة وثابتة، كما تعيده قائمة النتائج.
`output_target`	`str \| None`	`keyword-only`	`None`	external_srt أو external_vtt أو external_ass أو embedded؛ تستخدم None افتراض نقطة النهاية أو الحساب.

`export_project_operation_result`

تصدير آخر مرحلة ناجحة لعنصر مصدر واحد في العملية.

Python

export_project_operation_result(
    project_id: str,
    operation_id: str,
    content_id: str,
    *,
    output_target: str | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`content_id`	`str`	`positional-or-keyword`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`output_target`	`str \| None`	`keyword-only`	`None`	external_srt أو external_vtt أو external_ass أو embedded؛ تستخدم None افتراض نقطة النهاية أو الحساب.

`export_project_operation_result_names`

أسماء الملفات النهائية للنتائج المحددة التي تُكتب معاً في ملف ZIP واحد أو مجلد واحد. تحصل الأسماء التي قد تتعارض على رقم أصل المصدر أو على رقم تسلسلي (clip.en.3.srt).

Python

export_project_operation_result_names(
    project_id: str,
    operation_id: str,
    artifact_ids: list[str],
    *,
    output_target: str
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`artifact_ids`	`list[str]`	`positional-or-keyword`	—	معرّفات نواتج مراحل العملية الناجحة والثابتة التي تُكتب معاً، كما تعيدها قائمة النتائج.
`output_target`	`str`	`keyword-only`	—	external_srt أو external_vtt أو external_ass؛ لا تملك النتائج المضمّنة أسماء ملفات خاصة بها.

`generate_api_token`

توليد رمز API النشط الوحيد مع استبدال السابق؛ يتولى المستدعي الموافقة وحماية السر.

Python

generate_api_token() -> JsonValue

`get_api_token_status`

قراءة حالة الرمز دون استعادة سر موجود.

Python

get_api_token_status() -> JsonValue

`get_asset_document`

قراءة مستند ترجمة محفوظ ومتسق مع إصداره الحالي.

Python

get_asset_document(
    project_id: str, media_id: str, asset_id: str
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`positional-or-keyword`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.

`get_maintenance_status`

قراءة حالة صيانة البوابة دون مصادقة.

Python

get_maintenance_status() -> JsonValue

`get_media_asset`

قراءة أصل حالي واحد مع بيانات ارتباطه ولقطته.

Python

get_media_asset(
    project_id: str, media_id: str, asset_id: str
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`positional-or-keyword`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.

`get_operation`

قراءة الحالة العامة المعتمدة للعملية؛ طابقها بعد الأحداث وإعادة الاتصال.

Python

get_operation(operation_id: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.

`get_project`

قراءة مشروع مع نظرة عامة على جرده الحالي.

Python

get_project(project_id: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.

`get_project_media`

قراءة سجل وسائط مشروع حالي واحد.

Python

get_project_media(project_id: str, media_id: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.

`get_project_operation`

قراءة عملية عبر مسار المشروع الذي يملكها.

Python

get_project_operation(project_id: str, operation_id: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.

`get_session`

قراءة مورد الجلسة الموثّقة.

Python

get_session() -> JsonValue

`get_workflow_preferences`

قراءة افتراضات سير العمل والتصدير للحساب؛ يمكن أن تتجاوزها الخيارات الصريحة.

Python

get_workflow_preferences() -> JsonValue

`hide_media_asset`

إخفاء أصل باستخدام قيم التحقق الحالية مع الاحتفاظ بسجل إنتاجه.

Python

hide_media_asset(
    project_id: str,
    media_id: str,
    asset_id: str,
    *,
    expected_autosave_version: int | None = None,
    guards: Mapping[str, Any] | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`positional-or-keyword`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.
`expected_autosave_version`	`int \| None`	`keyword-only`	`None`	قيم التحقق الحالية للملاحظة أو الجيل أو الحفظ من استجابة القراءة أو بدء الفحص؛ تتطلب القيم القديمة قراءة جديدة.
`guards`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	قيم التحقق الحالية للملاحظة أو الجيل أو الحفظ من استجابة القراءة أو بدء الفحص؛ تتطلب القيم القديمة قراءة جديدة.

`import_project`

إنشاء مشروع من إعداد كامل للملفات والجرد المقدمين.

Python

import_project(
    *,
    name: str,
    mode: str,
    root_label: str | None = None,
    media: Iterable[Mapping[str, Any]] | None = None,
    file_evidence: Iterable[Mapping[str, Any]] | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`name`	`str`	`keyword-only`	—	اسم عرض المشروع؛ يمكن أن يستخدم update_project القيمة None لمسح قيمة تقبل الفراغ.
`mode`	`str`	`keyword-only`	—	وضع المشروع: file أو directory.
`root_label`	`str \| None`	`keyword-only`	`None`	تسمية مقروءة للمجلد أو الملف الجذر، وليست مساراً محلياً يمكن للخادم الوصول إليه.
`media`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.
`file_evidence`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	لقطة مجلد كاملة أو قائمة ملفات أو أدلة ملاحظة تتطلبها نقطة النهاية؛ أنشئها من الملفات المحلية.

`list_media_assets`

سرد الأصول المحفوظة التابعة لعنصر وسائط مشروع واحد.

Python

list_media_assets(
    project_id: str,
    media_id: str,
    *,
    limit: int = 50,
    offset: int = 0,
    content_type: str | None = None,
    kind: str | None = None,
    search: str | None = None,
    language: str | None = None,
    forced: bool | None = None,
    sdh: bool | None = None,
    commentary: bool | None = None,
    classification: str | None = None,
    readiness: str | None = None,
    placement: str | None = None,
    sort: str = 'created_at',
    direction: str = 'asc'
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`limit`	`int`	`keyword-only`	`50`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`offset`	`int`	`keyword-only`	`0`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`content_type`	`str \| None`	`keyword-only`	`None`	نوع MIME للبيانات المحضّرة؛ تتقدم ترويسة هدف الرفع إذا كانت تحدده بالفعل.
`kind`	`str \| None`	`keyword-only`	`None`	محدد خاص بنقطة النهاية لنوع الأصل أو نطاق الفحص أو الجاهزية أو الموضع؛ اتبع عقد نقطة النهاية.
`search`	`str \| None`	`keyword-only`	`None`	نص بحث اختياري لقائمة المشاريع أو الوسائط المطلوبة.
`language`	`str \| None`	`keyword-only`	`None`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`forced`	`bool \| None`	`keyword-only`	`None`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`sdh`	`bool \| None`	`keyword-only`	`None`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`commentary`	`bool \| None`	`keyword-only`	`None`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`classification`	`str \| None`	`keyword-only`	`None`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`readiness`	`str \| None`	`keyword-only`	`None`	محدد خاص بنقطة النهاية لنوع الأصل أو نطاق الفحص أو الجاهزية أو الموضع؛ اتبع عقد نقطة النهاية.
`placement`	`str \| None`	`keyword-only`	`None`	محدد خاص بنقطة النهاية لنوع الأصل أو نطاق الفحص أو الجاهزية أو الموضع؛ اتبع عقد نقطة النهاية.
`sort`	`str`	`keyword-only`	`'created_at'`	حقل الترتيب أو اتجاهه الذي تدعمه نقطة نهاية القائمة.
`direction`	`str`	`keyword-only`	`'asc'`	حقل الترتيب أو اتجاهه الذي تدعمه نقطة نهاية القائمة.

`list_operations`

سرد العمليات العامة مع تحديد الصفحات صراحةً.

Python

list_operations(*, limit: int = 50, offset: int = 0) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`limit`	`int`	`keyword-only`	`50`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`offset`	`int`	`keyword-only`	`0`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.

`list_project_media`

سرد وسائط المشروع مع المرشحات والصفحات؛ افحص total وstatus_counts.

Python

list_project_media(
    project_id: str,
    *,
    limit: int = 50,
    offset: int = 0,
    search: str | None = None,
    status: str = 'all',
    media_ids: Iterable[str] | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`limit`	`int`	`keyword-only`	`50`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`offset`	`int`	`keyword-only`	`0`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`search`	`str \| None`	`keyword-only`	`None`	نص بحث اختياري لقائمة المشاريع أو الوسائط المطلوبة.
`status`	`str`	`keyword-only`	`'all'`	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`media_ids`	`Iterable[str] \| None`	`keyword-only`	`None`	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.

`list_project_operation_results`

سرد نواتج المراحل الناجحة المحفوظة، بما فيها النتائج المفيدة من العمل الذي فشل جزئياً.

Python

list_project_operation_results(
    project_id: str, operation_id: str
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.

`list_project_operations`

سرد عمليات المشروع، مع إمكانية حصرها في عنصر وسائط واحد.

Python

list_project_operations(
    project_id: str,
    *,
    limit: int = 50,
    offset: int = 0,
    media_id: str | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`limit`	`int`	`keyword-only`	`50`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`offset`	`int`	`keyword-only`	`0`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`media_id`	`str \| None`	`keyword-only`	`None`	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.

`list_archived_projects`

عرض المشاريع المؤرشفة مع التصفية حسب الوضع والبحث والترتيب وتقسيم الصفحات. يُعرض الأحدث أرشفة أولًا افتراضيًا.

Python

list_archived_projects(
    *,
    limit: int = 50,
    offset: int = 0,
    mode: str | None = None,
    search: str | None = None,
    sort: str = 'archived_at',
    direction: str = 'desc'
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`limit`	`int`	`keyword-only`	`50`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`offset`	`int`	`keyword-only`	`0`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`mode`	`str \| None`	`keyword-only`	`None`	وضع المشروع: file أو directory.
`search`	`str \| None`	`keyword-only`	`None`	نص بحث اختياري لقائمة المشاريع أو الوسائط المطلوبة.
`sort`	`str`	`keyword-only`	`'archived_at'`	حقل الترتيب أو اتجاهه الذي تدعمه نقطة نهاية القائمة.
`direction`	`str`	`keyword-only`	`'desc'`	حقل الترتيب أو اتجاهه الذي تدعمه نقطة نهاية القائمة.

`list_projects`

عرض المشاريع النشطة مع التصفية حسب الوضع والبحث والترتيب وتقسيم الصفحات.

Python

list_projects(
    *,
    limit: int = 50,
    offset: int = 0,
    mode: str | None = None,
    search: str | None = None,
    sort: str = 'updated_at',
    direction: str = 'desc'
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`limit`	`int`	`keyword-only`	`50`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`offset`	`int`	`keyword-only`	`0`	حجم الصفحة أو إزاحة تبدأ من الصفر؛ تابع الصفحات حتى الوصول إلى العدد الإجمالي المعلن.
`mode`	`str \| None`	`keyword-only`	`None`	وضع المشروع: file أو directory.
`search`	`str \| None`	`keyword-only`	`None`	نص بحث اختياري لقائمة المشاريع أو الوسائط المطلوبة.
`sort`	`str`	`keyword-only`	`'updated_at'`	حقل الترتيب أو اتجاهه الذي تدعمه نقطة نهاية القائمة.
`direction`	`str`	`keyword-only`	`'desc'`	حقل الترتيب أو اتجاهه الذي تدعمه نقطة نهاية القائمة.

`materialize_asset`

تسجيل نص ترجمة مستخرج محلياً من مصدر فعلي باستخدام قيم تحقق حديثة للملاحظة.

Python

materialize_asset(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`positional-or-keyword`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`preview_project_directory_sync`

مقارنة لقطة محلية كاملة بالجرد الحالي قبل تطبيق التغييرات.

Python

preview_project_directory_sync(
    project_id: str, files: Iterable[Mapping[str, Any]]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`files`	`Iterable[Mapping[str, Any]]`	`positional-or-keyword`	—	لقطة مجلد كاملة أو قائمة ملفات أو أدلة ملاحظة تتطلبها نقطة النهاية؛ أنشئها من الملفات المحلية.

`preview_project_sidecars`

العثور على تطابقات الملفات الجانبية وحالات الالتباس قبل إرفاقها.

Python

preview_project_sidecars(
    project_id: str, sidecars: Iterable[Mapping[str, Any]]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`sidecars`	`Iterable[Mapping[str, Any]]`	`positional-or-keyword`	—	ملفات ترجمة جانبية تم فحصها مع بيانات الاقتران والتصنيف.

`put_upload_target`

الرفع مباشرةً باستخدام طريقة الخادم وترويساته؛ يُحذف رمز SubFT.

Python

put_upload_target(
    upload_url: str,
    *,
    method: str = 'PUT',
    data: Any | None = None,
    content: Any | None = None,
    headers: Mapping[str, str] | None = None,
    content_type: str = 'application/octet-stream'
) -> httpx.Response

المعامل	النوع	التمرير	الافتراض	المعنى
`upload_url`	`str`	`positional-or-keyword`	—	عنوان من API؛ تُحل العناوين النسبية مقابل البوابة. لا يُرسل رمز SubFT إلى عناوين الرفع.
`method`	`str`	`keyword-only`	`'PUT'`	طريقة HTTP؛ احتفظ بالطريقة الصادرة من الخادم عند الرفع المباشر.
`data`	`Any \| None`	`keyword-only`	`None`	بيانات النموذج أو الرفع التي يقبلها HTTPX؛ لا تجمعها مع content في الرفع المباشر.
`content`	`Any \| None`	`keyword-only`	`None`	بايتات خام أو مجموعة من كتل البايتات. استخدم الملف المحضّر للرفع.
`headers`	`Mapping[str, str] \| None`	`keyword-only`	`None`	ترويسات HTTP. مرّر ترويسات هدف الرفع دون تغيير؛ ترويسات الطلب العادي تتجاوز ترويسات المنشئ.
`content_type`	`str`	`keyword-only`	`'application/octet-stream'`	نوع MIME للبيانات المحضّرة؛ تتقدم ترويسة هدف الرفع إذا كانت تحدده بالفعل.

`register_verified_asset_outputs`

تسجيل المخرجات الفعلية المتحقق منها محلياً باستخدام التقاطها الثابت؛ لا يكفي التنزيل وحده.

Python

register_verified_asset_outputs(
    project_id: str, media_id: str, payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`remove_project_media`

إزالة عنصر وسائط من الجرد النشط عبر مسار المشروع.

Python

remove_project_media(project_id: str, media_id: str) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.

`replace_project_media`

مطابقة ملف وسائط محلي تغير باستخدام أدلة جرد جديدة.

Python

replace_project_media(
    project_id: str, media_id: str, media: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`media`	`Mapping[str, Any]`	`positional-or-keyword`	—	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.

`report_content_progress`

الإبلاغ عن تقدم العميل الخاص بالمحاولة وفق العقد الحالي ورقم مراجعة متزايد.

Python

report_content_progress(
    operation_id: str,
    media_id: str,
    content_id: str,
    payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`content_id`	`str`	`positional-or-keyword`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`request`

إرسال طلب HTTP وإعادة الاستجابة الخام بعد معالجة الأخطاء المشتركة.

Python

request(
    method: str,
    path: str,
    *,
    params: Mapping[str, Any] | None = None,
    json: JsonValue | None = None,
    data: Any | None = None,
    content: Any | None = None,
    headers: Mapping[str, str] | None = None,
    authenticated: bool = True
) -> httpx.Response

المعامل	النوع	التمرير	الافتراض	المعنى
`method`	`str`	`positional-or-keyword`	—	طريقة HTTP؛ احتفظ بالطريقة الصادرة من الخادم عند الرفع المباشر.
`path`	`str`	`positional-or-keyword`	—	مسار HTTP نسبة إلى base_url أو عنوان URL مطلق؛ ليس مساراً محلياً في نظام الملفات.
`params`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	معاملات الاستعلام؛ تُحذف قيم None والمجموعات الفارغة.
`json`	`JsonValue \| None`	`keyword-only`	`None`	محتوى طلب JSON، ويجب أن يطابق عقد نقطة النهاية.
`data`	`Any \| None`	`keyword-only`	`None`	بيانات النموذج أو الرفع التي يقبلها HTTPX؛ لا تجمعها مع content في الرفع المباشر.
`content`	`Any \| None`	`keyword-only`	`None`	بايتات خام أو مجموعة من كتل البايتات. استخدم الملف المحضّر للرفع.
`headers`	`Mapping[str, str] \| None`	`keyword-only`	`None`	ترويسات HTTP. مرّر ترويسات هدف الرفع دون تغيير؛ ترويسات الطلب العادي تتجاوز ترويسات المنشئ.
`authenticated`	`bool`	`keyword-only`	`True`	يحدد ما إذا كان العميل يضيف ترويسة تفويض SubFT. يستخدم الرفع المباشر False.

`request_json`

إرسال طلب HTTP وفك JSON؛ تعيد الاستجابات الفارغة None.

Python

request_json(
    method: str,
    path: str,
    *,
    params: Mapping[str, Any] | None = None,
    json: JsonValue | None = None,
    headers: Mapping[str, str] | None = None,
    authenticated: bool = True
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`method`	`str`	`positional-or-keyword`	—	طريقة HTTP؛ احتفظ بالطريقة الصادرة من الخادم عند الرفع المباشر.
`path`	`str`	`positional-or-keyword`	—	مسار HTTP نسبة إلى base_url أو عنوان URL مطلق؛ ليس مساراً محلياً في نظام الملفات.
`params`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	معاملات الاستعلام؛ تُحذف قيم None والمجموعات الفارغة.
`json`	`JsonValue \| None`	`keyword-only`	`None`	محتوى طلب JSON، ويجب أن يطابق عقد نقطة النهاية.
`headers`	`Mapping[str, str] \| None`	`keyword-only`	`None`	ترويسات HTTP. مرّر ترويسات هدف الرفع دون تغيير؛ ترويسات الطلب العادي تتجاوز ترويسات المنشئ.
`authenticated`	`bool`	`keyword-only`	`True`	يحدد ما إذا كان العميل يضيف ترويسة تفويض SubFT. يستخدم الرفع المباشر False.

`resolve_url`

حل عنوان نسبي من الخادم مقابل بوابة العميل.

Python

resolve_url(url: str) -> str

المعامل	النوع	التمرير	الافتراض	المعنى
`url`	`str`	`positional-or-keyword`	—	عنوان من API؛ تُحل العناوين النسبية مقابل البوابة. لا يُرسل رمز SubFT إلى عناوين الرفع.

`restore_project_media`

استعادة عنصر مؤرشف. يحتاج عنصر الفيديو أو الصوت إلى media، أي بيانات الجرد الحالية لملفه: تحتفظ المسارات غير المتغيرة بأصولها. ولا يحتاج عنصر الترجمة إلى شيء.

Python

restore_project_media(
    project_id: str, media_id: str, media: Mapping[str, Any] | None = None
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`media`	`Mapping[str, Any] \| None`	`positional-or-keyword`	`None`	سجل الجرد لملف العنصر كما في `replace_project_media`؛ يُحذف لعنصر الترجمة.

`retry_content_preparation`

بدء محاولة تحضير جديدة مؤهلة مع التحقق بمعرّف المحاولة السابقة؛ لا يبدأ ذلك عملية جديدة.

Python

retry_content_preparation(
    operation_id: str,
    media_id: str,
    content_id: str,
    *,
    attempt_id: str,
    previous_attempt_id: str
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`content_id`	`str`	`positional-or-keyword`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`attempt_id`	`str`	`keyword-only`	—	قيمة UUID جديدة يختارها المستدعي وتؤكدها استجابة التحضير؛ استخدمها في كل طلب يخص هذه المحاولة.
`previous_attempt_id`	`str`	`keyword-only`	—	معرّف المحاولة في أحدث حالة تحضير معتمدة، ويستخدم للتحقق عند إعادة المحاولة.

`revoke_api_token`

إلغاء الرمز النشط على الخادم؛ لا يؤدي حذف رمز محفوظ محلياً إلى ذلك.

Python

revoke_api_token() -> JsonValue

`save_media_asset_document`

حفظ المقاطع القابلة للتحرير مع قيم تحقق للّقطة والإصدار؛ تتطلب التعارضات قراءة جديدة للمستند.

Python

save_media_asset_document(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`positional-or-keyword`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`scan_project_directory`

طلب تصنيف لقطة محلية مقدمة من الخادم؛ لا يستطيع الخادم فحص قرص المستدعي.

Python

scan_project_directory(files: Iterable[str]) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`files`	`Iterable[str]`	`positional-or-keyword`	—	لقطة مجلد كاملة أو قائمة ملفات أو أدلة ملاحظة تتطلبها نقطة النهاية؛ أنشئها من الملفات المحلية.

`start_content_preparation`

بدء محاولة تحضير مسموح بها بقيمة UUID جديدة قبل التجزئة والرفع.

Python

start_content_preparation(
    operation_id: str, media_id: str, content_id: str, *, attempt_id: str
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`content_id`	`str`	`positional-or-keyword`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`attempt_id`	`str`	`keyword-only`	—	قيمة UUID جديدة يختارها المستدعي وتؤكدها استجابة التحضير؛ استخدمها في كل طلب يخص هذه المحاولة.

`update_content_preparation`

تحديث التحضير أو تجديد نبضه أو الإبلاغ عن فشل awaiting_retry برمز المحاولة نفسه.

Python

update_content_preparation(
    operation_id: str,
    media_id: str,
    content_id: str,
    attempt_id: str,
    payload: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`content_id`	`str`	`positional-or-keyword`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`attempt_id`	`str`	`positional-or-keyword`	—	قيمة UUID جديدة يختارها المستدعي وتؤكدها استجابة التحضير؛ استخدمها في كل طلب يخص هذه المحاولة.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`update_media_asset`

تحديث البيانات الوصفية المسموح بها للأصل مع الحفاظ على محتوى الترجمة.

Python

update_media_asset(
    project_id: str, media_id: str, asset_id: str, metadata: Mapping[str, Any]
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`media_id`	`str`	`positional-or-keyword`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`positional-or-keyword`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.
`metadata`	`Mapping[str, Any]`	`positional-or-keyword`	—	بيانات اللغة والتصنيف المسموح بها للأصل؛ لا يؤدي ذلك إلى تعديل مقاطع الترجمة.

`update_project`

تحديث حقول المشروع المقدمة. تختلف حقول _UNSET المحذوفة عن القيم الممسوحة صراحةً باستخدام None.

Python

update_project(
    project_id: str,
    *,
    name: str | None | object = _UNSET,
    root_label: str | None | object = _UNSET
) -> JsonValue

المعامل	النوع	التمرير	الافتراض	المعنى
`project_id`	`str`	`positional-or-keyword`	—	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`name`	`str \| None \| object`	`keyword-only`	`_UNSET`	اسم عرض المشروع؛ يمكن أن يستخدم update_project القيمة None لمسح قيمة تقبل الفراغ.
`root_label`	`str \| None \| object`	`keyword-only`	`_UNSET`	تسمية مقروءة للمجلد أو الملف الجذر، وليست مساراً محلياً يمكن للخادم الوصول إليه.

`verify_auth`

التحقق من بيانات الاعتماد الفعلية وقراءة هوية الحساب.

Python

verify_auth() -> JsonValue

صادرات الحزمة الأساسية

استورد من subft_client. تحتاج الدوال المحلية إلى الإضافة المحلية وأدوات النظام المختارة. افحص الأخطاء المعادة قبل تحديث الجرد لدى الخادم. يحتاج الاتصال الفوري إلى إضافته ولا يطابق حالة HTTP المعتمدة.

`JsonArray`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

JsonArray = list[Any]

`JsonObject`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

JsonObject = dict[str, Any]

`JsonValue`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

JsonValue = Any

`SubftApiError`

استثناء عام. التقط النوع المحدد عندما تختلف المعالجة؛ يغطي الاستثناء الأساسي الأنواع المشتقة. تحتفظ حقول المنشئ الاختيارية بحالة HTTP أو البيانات أو أدلة النقل كما يحدد النوع.

Python

SubftApiError(
    status_code: int,
    message: str,
    *,
    payload: Any | None = None,
    response: httpx.Response | None = None
) -> None

`SubftClient`

عميل عام أو سجل ثابت. تمثل الحقول أدلة محلية أو فورية معادة، وليست أمراً لبدء العمل. تعرض الدوال أدناه القيم المسجلة.

Python

SubftClient(
    base_url: str,
    *,
    token: str | None = None,
    timeout: float | httpx.Timeout = 30.0,
    headers: Mapping[str, str] | None = None,
    cookies: Mapping[str, str] | None = None,
    transport: httpx.BaseTransport | None = None
) -> None

`SubftError`

`SubftMaintenanceError`

Python

SubftMaintenanceError(
    status_code: int,
    message: str,
    *,
    payload: Any | None = None,
    response: httpx.Response | None = None,
    mode: str | None = None,
    maintenance_until: str | None = None
) -> None

`SubftTransportError`

Python

SubftTransportError(
    message: str, *, request_error: httpx.RequestError
) -> None

`version`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

__version__ = '0.1.0'

الأدوات والسجلات المحلية

استورد من subft_client.local. تحتاج الدوال المحلية إلى الإضافة المحلية وأدوات النظام المختارة. افحص الأخطاء المعادة قبل تحديث الجرد لدى الخادم. يحتاج الاتصال الفوري إلى إضافته ولا يطابق حالة HTTP المعتمدة.

`AUDIO_EXTENSIONS`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

AUDIO_EXTENSIONS = frozenset({'mp3', 'wav', 'flac', 'aac', 'ogg', 'm4a'})

`DEFAULT_HASH_CHUNK_SIZE`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

DEFAULT_HASH_CHUNK_SIZE = 4 * 1024 * 1024

`DirectorySnapshotFile`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`path`	`str`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`size_bytes`	`int`	`True`	—	حجم الملف أو النقل الفعلي أو تقدم البايتات المقاس.
`last_modified_ms`	`int`	`True`	—	وقت تعديل الملف الذي تمت ملاحظته بالمللي ثانية.
`mime_type`	`str \| None`	`True`	—	نوع MIME المكتشف؛ لا يثبت وحده دعم الترميز.
`file_kind`	`LocalFileKind`	`True`	—	امتداد معروف أو تصنيف الجرد أو الحاوية المفحوصة.
`file_fingerprint_hash`	`str \| None`	`False`	`None`	بصمة أو تجزئة مقاسة من المصدر؛ راع نوع البصمة في السجل.
`language_text_sample`	`str \| None`	`False`	`None`	نص ترجمة فعلي محدود يستخدم كدليل على اللغة.

Python

to_api_dict() -> JsonObject

`DirectorySnapshotResult`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`files`	`tuple[DirectorySnapshotFile, ...]`	`True`	—	لقطة مجلد كاملة أو قائمة ملفات أو أدلة ملاحظة تتطلبها نقطة النهاية؛ أنشئها من الملفات المحلية.
`failures`	`tuple[LocalFailure, ...]`	`True`	—	أخطاء مسجلة لكل عنصر؛ لا تجعل هذه القائمة إرسال جرد جزئي آمناً.

Python

to_api_dict() -> JsonObject

`ExtractedFile`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`path`	`Path`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`filename`	`str`	`True`	—	اسم الملف المحضّر مع امتداده الفعلي، لتحديد تنسيق التخزين.
`content_type`	`str`	`True`	—	نوع MIME للبيانات المحضّرة؛ تتقدم ترويسة هدف الرفع إذا كانت تحدده بالفعل.

Python

to_api_dict() -> JsonObject

`FfmpegTools`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`wrapper_available`	`bool`	`True`	—	تثبيت الأداة أو إصدارها أو تشخيصها المرصود؛ لا تثبت إضافات Python البرامج التنفيذية للنظام.
`ffmpeg_path`	`str \| None`	`True`	—	تثبيت الأداة أو إصدارها أو تشخيصها المرصود؛ لا تثبت إضافات Python البرامج التنفيذية للنظام.
`ffmpeg_version`	`str \| None`	`True`	—	تثبيت الأداة أو إصدارها أو تشخيصها المرصود؛ لا تثبت إضافات Python البرامج التنفيذية للنظام.
`ffmpeg_error`	`str \| None`	`True`	—	تثبيت الأداة أو إصدارها أو تشخيصها المرصود؛ لا تثبت إضافات Python البرامج التنفيذية للنظام.
`ffprobe_path`	`str \| None`	`True`	—	تثبيت الأداة أو إصدارها أو تشخيصها المرصود؛ لا تثبت إضافات Python البرامج التنفيذية للنظام.
`ffprobe_version`	`str \| None`	`True`	—	تثبيت الأداة أو إصدارها أو تشخيصها المرصود؛ لا تثبت إضافات Python البرامج التنفيذية للنظام.
`ffprobe_error`	`str \| None`	`True`	—	تثبيت الأداة أو إصدارها أو تشخيصها المرصود؛ لا تثبت إضافات Python البرامج التنفيذية للنظام.

Python

ffmpeg_available: bool

Python

ffprobe_available: bool

Python

available: bool

Python

to_api_dict() -> JsonObject

`FfmpegUnavailableError`

`FileFingerprint`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`kind`	`FingerprintKind`	`True`	—	محدد خاص بنقطة النهاية لنوع الأصل أو نطاق الفحص أو الجاهزية أو الموضع؛ اتبع عقد نقطة النهاية.
`hash`	`str`	`True`	—	بصمة أو تجزئة مقاسة من المصدر؛ راع نوع البصمة في السجل.

Python

to_api_dict() -> JsonObject

`GRAPHICAL_SUBTITLE_EXTENSIONS`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

GRAPHICAL_SUBTITLE_EXTENSIONS = frozenset({'sup', 'idx', 'sub'})

`InventoryResult`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`items`	`tuple[MediaInventoryItem, ...]`	`True`	—	سجلات جرد وسائط مفحوصة؛ افحص الأخطاء قبل إرسالها.
`failures`	`tuple[LocalFailure, ...]`	`True`	—	أخطاء مسجلة لكل عنصر؛ لا تجعل هذه القائمة إرسال جرد جزئي آمناً.
`total_candidates`	`int`	`True`	—	عدد مرشحات الفحص قبل استبعاد الملفات غير المدعومة أو الأخطاء.

Python

to_api_dict() -> JsonObject

`LANGUAGE_SAMPLE_BYTES`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

LANGUAGE_SAMPLE_BYTES = 64 * 1024

`LocalFailure`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`path`	`str`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`error_type`	`str`	`True`	—	بيانات تشخيص تقنية للسجلات الداخلية؛ يجب أن تحول الواجهات العامة الرموز إلى نص مترجم.
`message`	`str`	`True`	—	بيانات تشخيص تقنية للسجلات الداخلية؛ يجب أن تحول الواجهات العامة الرموز إلى نص مترجم.

Python

from_exception(path: str | Path, error: Exception) -> LocalFailure

Python

to_api_dict() -> JsonObject

`LocalFile`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`absolute_path`	`Path`	`True`	—	مسار محلي محسوم للمستدعي؛ لا تنشره في البحث العام.
`relative_path`	`str`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`size_bytes`	`int`	`True`	—	حجم الملف أو النقل الفعلي أو تقدم البايتات المقاس.
`last_modified_ms`	`int`	`True`	—	وقت تعديل الملف الذي تمت ملاحظته بالمللي ثانية.
`mime_type`	`str \| None`	`True`	—	نوع MIME المكتشف؛ لا يثبت وحده دعم الترميز.
`suffix`	`str`	`True`	—	امتداد معروف أو تصنيف الجرد أو الحاوية المفحوصة.
`file_kind`	`LocalFileKind`	`True`	—	امتداد معروف أو تصنيف الجرد أو الحاوية المفحوصة.

Python

to_api_dict() -> JsonObject

`LocalFileChangedError`

`LocalHashError`

`LocalPathError`

`LocalProgress`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`phase`	`ProgressPhase`	`True`	—	مرحلة التقدم المحلي وعدد العناصر أو البايتات المكتملة المقاس؛ الاستدعاءات متزامنة.
`path`	`str \| None`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`current`	`int`	`True`	—	مرحلة التقدم المحلي وعدد العناصر أو البايتات المكتملة المقاس؛ الاستدعاءات متزامنة.
`total`	`int`	`True`	—	مرحلة التقدم المحلي وعدد العناصر أو البايتات المكتملة المقاس؛ الاستدعاءات متزامنة.
`loaded_bytes`	`int \| None`	`False`	`None`	حجم الملف أو النقل الفعلي أو تقدم البايتات المقاس.
`total_bytes`	`int \| None`	`False`	`None`	حجم الملف أو النقل الفعلي أو تقدم البايتات المقاس.

Python

percent: float

Python

to_api_dict() -> JsonObject

`LocalScanError`

`MediaInventoryItem`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`path`	`str`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`display_name`	`str`	`True`	—	اسم العرض لعنصر الوسائط هذا الذي تمت ملاحظته محلياً.
`size_bytes`	`int`	`True`	—	حجم الملف أو النقل الفعلي أو تقدم البايتات المقاس.
`last_modified_ms`	`int`	`True`	—	وقت تعديل الملف الذي تمت ملاحظته بالمللي ثانية.
`mime_type`	`str \| None`	`True`	—	نوع MIME المكتشف؛ لا يثبت وحده دعم الترميز.
`file_fingerprint_hash`	`str \| None`	`True`	—	بصمة أو تجزئة مقاسة من المصدر؛ راع نوع البصمة في السجل.
`duration_seconds`	`float`	`True`	—	المدة المقاسة بالثواني، وليست وقت معالجة مضموناً.
`container_format`	`str \| None`	`True`	—	امتداد معروف أو تصنيف الجرد أو الحاوية المفحوصة.
`probe_data`	`JsonObject \| None`	`True`	—	أدلة الحاوية والمسارات الفعلية من FFprobe؛ تحتفظ الخرائط المفتوحة بحقول الفحص.
`streams`	`tuple[ProbeStream, ...]`	`True`	—	سجلات مسارات صوت أو ترجمة موحّدة مع أرقام المسارات الأصلية.
`status`	`str`	`False`	`'active'`	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.

Python

to_api_dict() -> JsonObject

`MediaEmbeddingError`

`MediaExtractionError`

`MediaProbe`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`duration_seconds`	`float`	`True`	—	المدة المقاسة بالثواني، وليست وقت معالجة مضموناً.
`has_audio`	`bool`	`True`	—	يحدد ما إذا كان المسار أو المصدر المرصود قابلاً للاختيار أو يحتوي على صوت.
`streams`	`tuple[ProbeStream, ...]`	`True`	—	سجلات مسارات صوت أو ترجمة موحّدة مع أرقام المسارات الأصلية.
`format`	`JsonObject`	`True`	—	أدلة الحاوية والمسارات الفعلية من FFprobe؛ تحتفظ الخرائط المفتوحة بحقول الفحص.
`raw_streams`	`tuple[JsonObject, ...]`	`True`	—	أدلة الحاوية والمسارات الفعلية من FFprobe؛ تحتفظ الخرائط المفتوحة بحقول الفحص.

Python

to_api_dict() -> JsonObject

`MediaProbeError`

`MuxedMedia`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`path`	`Path`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`size_bytes`	`int`	`True`	—	حجم الملف أو النقل الفعلي أو تقدم البايتات المقاس.
`last_modified_ms`	`int`	`True`	—	وقت تعديل الملف الذي تمت ملاحظته بالمللي ثانية.

Python

to_api_dict() -> JsonObject

`ProbeStream`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`stream_index`	`int \| None`	`True`	—	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.
`stream_type`	`str`	`True`	—	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`stream_class`	`StreamClass`	`True`	—	التصنيف العادي أو أي مجموعة من التعليق والإجباري وSDH.
`codec_type`	`str`	`True`	—	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`codec_name`	`str \| None`	`True`	—	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`language`	`str \| None`	`True`	—	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`tags`	`JsonObject \| None`	`True`	—	بيانات المسار الحالية والأدلة الفعلية المستخدمة للتحقق من الملاحظة.
`disposition`	`JsonObject \| None`	`True`	—	بيانات المسار الحالية والأدلة الفعلية المستخدمة للتحقق من الملاحظة.
`selectable`	`bool`	`False`	`True`	يحدد ما إذا كان المسار أو المصدر المرصود قابلاً للاختيار أو يحتوي على صوت.
`language_text_sample`	`str \| None`	`False`	`None`	نص ترجمة فعلي محدود يستخدم كدليل على اللغة.
`sidecar_path`	`str \| None`	`False`	`None`	هوية الملف المرافق وأدلته المرصودة؛ احتفظ بزوج الملفات المتطابق.
`sidecar_display_name`	`str \| None`	`False`	`None`	هوية الملف المرافق وأدلته المرصودة؛ احتفظ بزوج الملفات المتطابق.
`sidecar_size_bytes`	`int \| None`	`False`	`None`	هوية الملف المرافق وأدلته المرصودة؛ احتفظ بزوج الملفات المتطابق.
`sidecar_last_modified_ms`	`int \| None`	`False`	`None`	هوية الملف المرافق وأدلته المرصودة؛ احتفظ بزوج الملفات المتطابق.
`sidecar_content_hash`	`str \| None`	`False`	`None`	هوية الملف المرافق وأدلته المرصودة؛ احتفظ بزوج الملفات المتطابق.
`source_observation`	`JsonObject \| None`	`False`	`None`	بيانات المسار الحالية والأدلة الفعلية المستخدمة للتحقق من الملاحظة.
`text_content`	`str \| None`	`False`	`None`	نص الترجمة الكامل الذي تخزنه مشاريع الملفات؛ وتكون القيمة `None` للمسارات الأخرى.

Python

to_api_dict() -> JsonObject

`SUBTITLE_EXTENSIONS`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

SUBTITLE_EXTENSIONS = frozenset({'srt', 'vtt', 'ass'})

`ScanResult`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`files`	`tuple[LocalFile, ...]`	`True`	—	لقطة مجلد كاملة أو قائمة ملفات أو أدلة ملاحظة تتطلبها نقطة النهاية؛ أنشئها من الملفات المحلية.
`failures`	`tuple[LocalFailure, ...]`	`True`	—	أخطاء مسجلة لكل عنصر؛ لا تجعل هذه القائمة إرسال جرد جزئي آمناً.

Python

to_api_dict() -> JsonObject

`SubftLocalError`

`SubtitleMuxInput`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`path`	`Path`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`language`	`str \| None`	`False`	`None`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`stream_class`	`StreamClass`	`False`	`'normal'`	التصنيف العادي أو أي مجموعة من التعليق والإجباري وSDH.

`VIDEO_EXTENSIONS`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

VIDEO_EXTENSIONS = frozenset({'mp4', 'mkv', 'avi', 'mov', 'webm'})

`VOBSUB_EXTENSIONS`

ثابت عام أو اسم مستعار لنوع. تأتي القيمة أدناه من المصدر؛ تحتفظ المعرّفات والوحدات بمعناها التقني.

Python

VOBSUB_EXTENSIONS = frozenset({'idx', 'sub'})

`build_directory_snapshot`

إنشاء ملفات كاملة وبصمات وعينات لغوية محدودة لمطابقة المجلد.

Python

build_directory_snapshot(
    source: FileCollection,
    *,
    include_hidden: bool = False,
    hash_media_paths: Iterable[str | os.PathLike[str]] = (),
    include_text_samples: bool = False,
    on_progress: ProgressCallback | None = None
) -> DirectorySnapshotResult

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`FileCollection`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`include_hidden`	`bool`	`keyword-only`	`False`	تضمين الملفات والمجلدات التي تبدأ بنقطة عند True؛ تبقى الروابط الرمزية مستبعدة.
`hash_media_paths`	`Iterable[str \| os.PathLike[str]]`	`keyword-only`	`()`	مسارات الوسائط النسبية التي تحتاج لقطة المجلد إلى بصماتها.
`include_text_samples`	`bool`	`keyword-only`	`False`	تضمين عينات محدودة من لغة الترجمة أو تحديد أقصى عدد لبايتات المصدر.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	استدعاء متزامن يستقبل LocalProgress. رفع استثناء يوقف العمل، وتنتقل أخطاء الاستدعاء إلى المستدعي.

`build_inventory`

فحص الوسائط لتكوين جرد جاهز لـ API؛ يجب معالجة كل خطأ مسجل قبل الإرسال.

Python

build_inventory(
    source: FileCollection,
    *,
    include_hidden: bool = False,
    ffprobe_executable: str = 'ffprobe',
    probe_timeout: float = 30.0,
    on_progress: ProgressCallback | None = None
) -> InventoryResult

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`FileCollection`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`include_hidden`	`bool`	`keyword-only`	`False`	تضمين الملفات والمجلدات التي تبدأ بنقطة عند True؛ تبقى الروابط الرمزية مستبعدة.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`probe_timeout`	`float`	`keyword-only`	`30.0`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	استدعاء متزامن يستقبل LocalProgress. رفع استثناء يوقف العمل، وتنتقل أخطاء الاستدعاء إلى المستدعي.

`check_ffmpeg_tools`

إعادة توفر الأدوات دون اشتراط وجودها كلها.

Python

check_ffmpeg_tools(
    *,
    ffmpeg_executable: str = 'ffmpeg',
    ffprobe_executable: str = 'ffprobe',
    timeout: float = 5.0
) -> FfmpegTools

المعامل	النوع	التمرير	الافتراض	المعنى
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`timeout`	`float`	`keyword-only`	`5.0`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.

`count_pgs_images`

عد صور الترجمة الرسومية من المصدر الفعلي؛ يتطلب VobSub كلا الملفين.

Python

count_pgs_images(content: bytes) -> int

المعامل	النوع	التمرير	الافتراض	المعنى
`content`	`bytes`	`positional-or-keyword`	—	بايتات خام أو مجموعة من كتل البايتات. استخدم الملف المحضّر للرفع.

`count_vobsub_images`

عد صور الترجمة الرسومية من المصدر الفعلي؛ يتطلب VobSub كلا الملفين.

Python

count_vobsub_images(text: str) -> int

المعامل	النوع	التمرير	الافتراض	المعنى
`text`	`str`	`positional-or-keyword`	—	نص الترجمة الفعلي أو تنسيقه SRT/VTT/ASS؛ تُوحّد المقاييس التنسيق بدلاً من عد بايتات الملف الخام.

`embed_subtitle_tracks`

كتابة خرج مدمج يملكه المستدعي مع الحفاظ على المسارات الأخرى؛ التثبيت والتسجيل خطوتان منفصلتان.

Python

embed_subtitle_tracks(
    source: LocalSource,
    subtitles: Iterable[SubtitleMuxInput],
    output_path: str | os.PathLike[str],
    *,
    ffmpeg_executable: str = 'ffmpeg',
    ffprobe_executable: str = 'ffprobe',
    timeout: float = 1800.0,
    on_progress: ProgressCallback | None = None,
    replace_stream_indexes: Iterable[int] = ()
) -> MuxedMedia

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`LocalSource`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`subtitles`	`Iterable[SubtitleMuxInput]`	`positional-or-keyword`	—	سجلات SubtitleMuxInput تحدد ملفات SRT فعلية واللغات وتصنيفات المسارات المراد إضافتها.
`output_path`	`str \| os.PathLike[str]`	`positional-or-keyword`	—	مسار خرج جديد يملكه المستدعي. لا تستبدل أدوات الاستخراج والدمج الأصل ولا تسجل أصولاً لدى الخادم.
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`timeout`	`float`	`keyword-only`	`1800.0`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	استدعاء متزامن يستقبل LocalProgress. رفع استثناء يوقف العمل، وتنتقل أخطاء الاستدعاء إلى المستدعي.
`replace_stream_indexes`	`Iterable[int]`	`keyword-only`	`()`	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.

`extract_audio_stream`

استخراج مسار صوت مختار بصيغة MP3 دون تغيير الأصل.

Python

extract_audio_stream(
    source: LocalSource,
    stream_index: int,
    output_path: str | os.PathLike[str],
    *,
    ffmpeg_executable: str = 'ffmpeg',
    timeout: float = 1800.0,
    on_progress: ProgressCallback | None = None
) -> ExtractedFile

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`LocalSource`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`stream_index`	`int`	`positional-or-keyword`	—	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.
`output_path`	`str \| os.PathLike[str]`	`positional-or-keyword`	—	مسار خرج جديد يملكه المستدعي. لا تستبدل أدوات الاستخراج والدمج الأصل ولا تسجل أصولاً لدى الخادم.
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`timeout`	`float`	`keyword-only`	`1800.0`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	استدعاء متزامن يستقبل LocalProgress. رفع استثناء يوقف العمل، وتنتقل أخطاء الاستدعاء إلى المستدعي.

`extract_subtitle_stream`

استخراج النص بصيغة SRT أو نسخ الترجمة الرسومية إلى Matroska؛ يتولى المستدعي التنظيف.

Python

extract_subtitle_stream(
    source: LocalSource,
    stream_index: int,
    output_path: str | os.PathLike[str],
    *,
    graphical: bool = False,
    source_format: str = 'srt',
    ffmpeg_executable: str = 'ffmpeg',
    timeout: float = 1800.0,
    on_progress: ProgressCallback | None = None
) -> ExtractedFile

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`LocalSource`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`stream_index`	`int`	`positional-or-keyword`	—	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.
`output_path`	`str \| os.PathLike[str]`	`positional-or-keyword`	—	مسار خرج جديد يملكه المستدعي. لا تستبدل أدوات الاستخراج والدمج الأصل ولا تسجل أصولاً لدى الخادم.
`graphical`	`bool`	`keyword-only`	`False`	يحدد ما إذا كان الاستخراج ينسخ مسار ترجمة رسومية إلى Matroska بدلاً من إنشاء SRT.
`source_format`	`str`	`keyword-only`	`'srt'`	نص الترجمة الفعلي أو تنسيقه SRT/VTT/ASS؛ تُوحّد المقاييس التنسيق بدلاً من عد بايتات الملف الخام.
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`timeout`	`float`	`keyword-only`	`1800.0`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	استدعاء متزامن يستقبل LocalProgress. رفع استثناء يوقف العمل، وتنتقل أخطاء الاستدعاء إلى المستدعي.

`fingerprint_media_file`

حساب بصمة وسائط كاملة أو جزئية متوافقة ورفض تغير المصدر.

Python

fingerprint_media_file(
    source: LocalSource,
    *,
    chunk_size: int = DEFAULT_HASH_CHUNK_SIZE,
    on_progress: ProgressCallback | None = None
) -> FileFingerprint

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`LocalSource`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`chunk_size`	`int`	`keyword-only`	`DEFAULT_HASH_CHUNK_SIZE`	عدد موجب للبايتات المقروءة في كل كتلة تجزئة؛ احتفظ بالافتراض لتوافق البصمات الجزئية.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	استدعاء متزامن يستقبل LocalProgress. رفع استثناء يوقف العمل، وتنتقل أخطاء الاستدعاء إلى المستدعي.

`hash_file_sha256`

قراءة كل البايتات لتكوين FileFingerprint بتجزئة SHA-256؛ استخدم حقل hash لطلبات API.

Python

hash_file_sha256(
    source: LocalSource,
    *,
    chunk_size: int = DEFAULT_HASH_CHUNK_SIZE,
    on_progress: ProgressCallback | None = None
) -> FileFingerprint

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`LocalSource`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`chunk_size`	`int`	`keyword-only`	`DEFAULT_HASH_CHUNK_SIZE`	عدد موجب للبايتات المقروءة في كل كتلة تجزئة؛ احتفظ بالافتراض لتوافق البصمات الجزئية.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	استدعاء متزامن يستقبل LocalProgress. رفع استثناء يوقف العمل، وتنتقل أخطاء الاستدعاء إلى المستدعي.

`hash_text_subtitle`

تجزئة نص الترجمة بعد توحيد الأسطر والمسافات المحيطة.

Python

hash_text_subtitle(source: LocalSource) -> FileFingerprint

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`LocalSource`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.

`inspect_media`

فحص ملف مدعوم واحد وإعادة أدلة الفحص والملاحظات الفعلية للمصدر.

Python

inspect_media(
    source: LocalFile | str | os.PathLike[str],
    *,
    relative_path: str | None = None,
    ffprobe_executable: str = 'ffprobe',
    probe_timeout: float = 30.0,
    on_progress: ProgressCallback | None = None,
    file_project: bool = False
) -> MediaInventoryItem

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`LocalFile \| str \| os.PathLike[str]`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`relative_path`	`str \| None`	`keyword-only`	`None`	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`probe_timeout`	`float`	`keyword-only`	`30.0`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	استدعاء متزامن يستقبل LocalProgress. رفع استثناء يوقف العمل، وتنتقل أخطاء الاستدعاء إلى المستدعي.
`file_project`	`bool`	`keyword-only`	`False`	تطبيق قواعد مشاريع الملفات: تضمين نص الترجمة الكامل ورفض ملفات الترجمة الرسومية.

`pgs_duration_seconds`

حساب مدة الترجمة بالثواني من التوقيت الفعلي للمقاطع أو الصور.

Python

pgs_duration_seconds(content: bytes) -> float

المعامل	النوع	التمرير	الافتراض	المعنى
`content`	`bytes`	`positional-or-keyword`	—	بايتات خام أو مجموعة من كتل البايتات. استخدم الملف المحضّر للرفع.

`probe_media`

قراءة مدة FFprobe والمسارات وأدلة الحاوية دون تعديل الملف.

Python

probe_media(
    source: LocalSource,
    *,
    ffprobe_executable: str = 'ffprobe',
    timeout: float = 30.0
) -> MediaProbe

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`LocalSource`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`timeout`	`float`	`keyword-only`	`30.0`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.

`read_subtitle_language_sample`

قراءة عينة محدودة من نص المصدر لتصنيف اللغة.

Python

read_subtitle_language_sample(
    source: LocalSource, *, max_bytes: int = LANGUAGE_SAMPLE_BYTES
) -> str | None

المعامل	النوع	التمرير	الافتراض	المعنى
`source`	`LocalSource`	`positional-or-keyword`	—	ملف مصدر محلي موجود أو سجل LocalFile أو مجموعة ملفات كما يحدد النوع؛ افحص الأخطاء قبل إرسال الجرد.
`max_bytes`	`int`	`keyword-only`	`LANGUAGE_SAMPLE_BYTES`	تضمين عينات محدودة من لغة الترجمة أو تحديد أقصى عدد لبايتات المصدر.

`require_ffmpeg_tools`

اشتراط الأدوات المحددة ورفع FfmpegUnavailableError إذا كانت المتطلبات مفقودة.

Python

require_ffmpeg_tools(
    *,
    ffmpeg_executable: str = 'ffmpeg',
    ffprobe_executable: str = 'ffprobe',
    timeout: float = 5.0,
    require_ffmpeg: bool = True,
    require_ffprobe: bool = True
) -> FfmpegTools

المعامل	النوع	التمرير	الافتراض	المعنى
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	اسم البرنامج التنفيذي للنظام أو مساره؛ تثبيت إضافة Python لا يثبت هذه البرامج.
`timeout`	`float`	`keyword-only`	`5.0`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.
`require_ffmpeg`	`bool`	`keyword-only`	`True`	يحدد ما إذا كان هذا الفحص يتطلب توفر البرنامج التنفيذي المقابل.
`require_ffprobe`	`bool`	`keyword-only`	`True`	يحدد ما إذا كان هذا الفحص يتطلب توفر البرنامج التنفيذي المقابل.

`scan_directory`

فحص حتمي مع تجاوز الروابط الرمزية وتسجيل الأخطاء لكل مسار.

Python

scan_directory(
    root: str | os.PathLike[str],
    *,
    include_hidden: bool = False,
    on_progress: ProgressCallback | None = None
) -> ScanResult

المعامل	النوع	التمرير	الافتراض	المعنى
`root`	`str \| os.PathLike[str]`	`positional-or-keyword`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`include_hidden`	`bool`	`keyword-only`	`False`	تضمين الملفات والمجلدات التي تبدأ بنقطة عند True؛ تبقى الروابط الرمزية مستبعدة.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	استدعاء متزامن يستقبل LocalProgress. رفع استثناء يوقف العمل، وتنتقل أخطاء الاستدعاء إلى المستدعي.

`subtitle_duration_seconds`

حساب مدة الترجمة بالثواني من التوقيت الفعلي للمقاطع أو الصور.

Python

subtitle_duration_seconds(
    text: str, format_hint: str | None = None
) -> float

المعامل	النوع	التمرير	الافتراض	المعنى
`text`	`str`	`positional-or-keyword`	—	نص الترجمة الفعلي أو تنسيقه SRT/VTT/ASS؛ تُوحّد المقاييس التنسيق بدلاً من عد بايتات الملف الخام.
`format_hint`	`str \| None`	`positional-or-keyword`	`None`	نص الترجمة الفعلي أو تنسيقه SRT/VTT/ASS؛ تُوحّد المقاييس التنسيق بدلاً من عد بايتات الملف الخام.

`vobsub_duration_seconds`

حساب مدة الترجمة بالثواني من التوقيت الفعلي للمقاطع أو الصور.

Python

vobsub_duration_seconds(text: str) -> float

المعامل	النوع	التمرير	الافتراض	المعنى
`text`	`str`	`positional-or-keyword`	—	نص الترجمة الفعلي أو تنسيقه SRT/VTT/ASS؛ تُوحّد المقاييس التنسيق بدلاً من عد بايتات الملف الخام.

`vobsub_pair_hash`

دمج بصمتي IDX وSUB المتطابقتين بالترتيب الحتمي الموثق.

Python

vobsub_pair_hash(idx_hash: str, sub_hash: str) -> str

المعامل	النوع	التمرير	الافتراض	المعنى
`idx_hash`	`str`	`positional-or-keyword`	—	تجزئتا ملفي IDX وSUB المتطابقين فعلياً، لتكوين تجزئة ثابتة للمصدر المزدوج.
`sub_hash`	`str`	`positional-or-keyword`	—	تجزئتا ملفي IDX وSUB المتطابقين فعلياً، لتكوين تجزئة ثابتة للمصدر المزدوج.

`visible_subtitle_character_count`

عد محارف الترجمة المرئية وفق قواعد توحيد الفوترة.

Python

visible_subtitle_character_count(
    text: str, format_hint: str | None = None
) -> int

المعامل	النوع	التمرير	الافتراض	المعنى
`text`	`str`	`positional-or-keyword`	—	نص الترجمة الفعلي أو تنسيقه SRT/VTT/ASS؛ تُوحّد المقاييس التنسيق بدلاً من عد بايتات الملف الخام.
`format_hint`	`str \| None`	`positional-or-keyword`	`None`	نص الترجمة الفعلي أو تنسيقه SRT/VTT/ASS؛ تُوحّد المقاييس التنسيق بدلاً من عد بايتات الملف الخام.

الأدوات والسجلات الفورية

استورد من subft_client.realtime. تحتاج الدوال المحلية إلى الإضافة المحلية وأدوات النظام المختارة. افحص الأخطاء المعادة قبل تحديث الجرد لدى الخادم. يحتاج الاتصال الفوري إلى إضافته ولا يطابق حالة HTTP المعتمدة.

`OperationEvent`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`event`	`str`	`True`	—	بيانات حدث أو اتصال فوري؛ اقرأ حالة HTTP المعتمدة قبل تحديد النتيجة.
`operation_id`	`str`	`True`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`content_id`	`str \| None`	`True`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`session_id`	`str \| None`	`True`	—	بيانات حدث أو اتصال فوري؛ اقرأ حالة HTTP المعتمدة قبل تحديد النتيجة.
`status`	`str \| None`	`True`	—	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`payload`	`Mapping[str, Any]`	`True`	—	خريطة طلب خاصة بنقطة النهاية. استخدم مخططها واحتفظ بقيم التحقق المطلوبة للملاحظة أو التحضير.

`RealtimeConnectionState`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`status`	`ConnectionStatus`	`True`	—	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`attempt`	`int`	`True`	—	بيانات حدث أو اتصال فوري؛ اقرأ حالة HTTP المعتمدة قبل تحديد النتيجة.
`reconnected`	`bool`	`True`	—	يحدد ما إذا كان الحدث يلي إعادة اتصال ناجحة؛ اقرأ الحالة المعتمدة مجدداً.
`reason`	`str \| None`	`False`	`None`	السبب التقني لحالة الاتصال هذه؛ استخدم حالة HTTP المعتمدة لتحديد الاسترداد.

`RealtimeDependencyError`

`RealtimeProtocolError`

`RealtimeSubscriptionError`

Python

RealtimeSubscriptionError(code: str='request_failed', params: Mapping[str, Any] | None=None)

تستخدم حالات رفض الاشتراك الآني event: "failed" مع واصف {code, params} في payload.error. يتيح RealtimeSubscriptionError الحقلين code وparams؛ نص التشخيص ليس عقداً للعرض.

`SubftRealtimeError`

`watch_operation_events`

إعادة أحداث العملية وتغيرات الاتصال مع إعادة الاتصال؛ تبقى مطابقة حالة HTTP المعتمدة مسؤولية المستدعي.

Python

watch_operation_events(
    base_url: str,
    operation_id: str,
    *,
    token: str,
    heartbeat_interval: float = DEFAULT_HEARTBEAT_INTERVAL,
    pong_timeout: float = DEFAULT_PONG_TIMEOUT,
    subscribe_timeout: float = DEFAULT_SUBSCRIBE_TIMEOUT,
    reconnect_initial_delay: float = DEFAULT_RECONNECT_INITIAL_DELAY,
    reconnect_max_delay: float = DEFAULT_RECONNECT_MAX_DELAY,
    _sleep: Callable[[float], Awaitable[None]] = asyncio.sleep
) -> AsyncGenerator[RealtimeMessage, None]

المعامل	النوع	التمرير	الافتراض	المعنى
`base_url`	`str`	`positional-or-keyword`	—	عنوان البوابة التي تقدم مسارات API والمصادقة والاتصال الفوري؛ تُوحّد الشرطة المائلة الأخيرة.
`operation_id`	`str`	`positional-or-keyword`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`token`	`str`	`keyword-only`	—	رمز API من صفحة وصول المطورين. احفظه في متغير بيئة محمي.
`heartbeat_interval`	`float`	`keyword-only`	`DEFAULT_HEARTBEAT_INTERVAL`	فترة نبض الاتصال أو انتظار pong أو إعادة الاتصال بالثواني؛ تستخدم إعادة الاتصال تأخيراً متزايداً محدوداً.
`pong_timeout`	`float`	`keyword-only`	`DEFAULT_PONG_TIMEOUT`	فترة نبض الاتصال أو انتظار pong أو إعادة الاتصال بالثواني؛ تستخدم إعادة الاتصال تأخيراً متزايداً محدوداً.
`subscribe_timeout`	`float`	`keyword-only`	`DEFAULT_SUBSCRIBE_TIMEOUT`	المهلة بالثواني؛ راجع التوقيع لمعرفة القيمة الافتراضية للطلب أو الفحص أو الاشتراك.
`reconnect_initial_delay`	`float`	`keyword-only`	`DEFAULT_RECONNECT_INITIAL_DELAY`	فترة نبض الاتصال أو انتظار pong أو إعادة الاتصال بالثواني؛ تستخدم إعادة الاتصال تأخيراً متزايداً محدوداً.
`reconnect_max_delay`	`float`	`keyword-only`	`DEFAULT_RECONNECT_MAX_DELAY`	فترة نبض الاتصال أو انتظار pong أو إعادة الاتصال بالثواني؛ تستخدم إعادة الاتصال تأخيراً متزايداً محدوداً.
`_sleep`	`Callable[[float], Awaitable[None]]`	`keyword-only`	`asyncio.sleep`	دالة انتظار غير متزامنة اختيارية للاختبارات الحتمية؛ تحتفظ التكاملات العادية بالافتراض.

مخططات الطلب والاستجابة

تعيد الجداول الحقول المعلنة بما فيها الموروثة. يستخدم عمود مطلوب True/False. تعني الشرطة عدم وجود تصريح افتراضي؛ تعرض Field(...) افتراضات Pydantic وقيوده الفعلية. قد تكون الحقول التي تقبل الفراغ مطلوبة أيضاً. تصف الأنواع المسماة سجلات متداخلة؛ تبقى dict[str, Any] مفتوحة عمداً وليست مخططاً شاملاً مخترعاً. تعيد أهداف الرفع أيضاً upload_id وoperation_id وmedia_id وcontent_id وupload_url وmethod وheaders وexpires_at وsidecar الاختياري؛ احتفظ بهويتها وانتهائها وطريقتها. يتحقق المثال الكامل من الحقول التي يستخدمها.

`AssetSelection`

عقد مشتق من المصدر. احتفظ بالحقول المطلوبة وقيم التحقق عند تكييف المثال؛ تختلف القيم التي تقبل الفراغ عن الحقول المطلوبة المفقودة.

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`media_id`	`str`	`True`	`Field(max_length=64)`	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`True`	`Field(max_length=64)`	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.
`source_language`	`str`	`True`	`Field(max_length=32)`	لغة المصدر الموحّدة الملتقطة مع الاختيار المحمي.
`expected_snapshot_id`	`str \| None`	`False`	`Field(default=None, max_length=64)`	اللقطة الثابتة الحالية أو جيل الفحص الفعلي المستخدم لتثبيت المصدر.
`expected_autosave_version`	`int \| None`	`False`	`None`	قيم التحقق الحالية للملاحظة أو الجيل أو الحفظ من استجابة القراءة أو بدء الفحص؛ تتطلب القيم القديمة قراءة جديدة.
`expected_observation`	`SourceObservation \| None`	`False`	`None`	أدلة الملفات والمسارات الفعلية التي يجب أن تظل مطابقة عند الاعتماد.
`check_generation`	`int \| None`	`False`	`None`	اللقطة الثابتة الحالية أو جيل الفحص الفعلي المستخدم لتثبيت المصدر.

`CapturedExport`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`asset_id`	`str`	`True`	`Field(max_length=64)`	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.
`snapshot_id`	`str`	`True`	`Field(max_length=64)`	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`autosave_version`	`int \| None`	`True`	—	إصدار الحفظ الحالي للتحرير، ويستخدم لاكتشاف التعديلات المتزامنة.
`effective_metadata`	`EffectiveMetadata`	`True`	—	لغة الحاوية الملتقطة أو اللغة والتصنيف الفعليان للخرج.
`container_language`	`str`	`True`	`Field(max_length=32)`	لغة الحاوية الملتقطة أو اللغة والتصنيف الفعليان للخرج.
`format`	`Literal['srt', 'vtt', 'ass']`	`True`	—	أدلة الحاوية والمسارات الفعلية من FFprobe؛ تحتفظ الخرائط المفتوحة بحقول الفحص.
`options`	`ExportOptions`	`False`	`Field(default_factory=ExportOptions)`	هوية وجهة التصدير أو خيارات التصدير الخاصة بنقطة النهاية.
`mime_type`	`str`	`True`	`Field(max_length=255)`	نوع MIME المكتشف؛ لا يثبت وحده دعم الترميز.
`suggested_path`	`str`	`True`	`Field(max_length=2048)`	بيانات تصدير ثابتة أو اسم ملف نسبي مقترح من الخادم أو نص الترجمة المتسلسل الفعلي.
`serializer_version`	`int`	`True`	—	إصدار المحلل أو أداة تسلسل التصدير المستخدمة للمستند الملتقط.
`parser_version`	`int`	`True`	—	إصدار المحلل أو أداة تسلسل التصدير المستخدمة للمستند الملتقط.
`text_content`	`str`	`True`	`Field(max_length=20000000)`	بيانات تصدير ثابتة أو اسم ملف نسبي مقترح من الخادم أو نص الترجمة المتسلسل الفعلي.

`CommittedSource`

قيمة ضمن source_ref_map بمفتاح معرّف وسائط المشروع:معرّف الأصل. استخدم media_id وcontent_id أثناء التشغيل للتحضير والرفع؛ تحدد الخطط المصادر باستخدام source_ref.

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`media_id`	`str`	`True`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`content_id`	`str`	`True`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`project_media_id`	`str`	`True`	—	العلاقة بين وسائط العملية والمشروع مع مسار الوسائط النسبي المسجل.

`ContentFlow`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`status`	`str`	`True`	—	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`step`	`str`	`True`	—	خطوة تنفيذ تقرؤها الآلة؛ استخدم نوع التدفق أو التقدم الحاوي وقيمه المعدودة.
`execution_count`	`int`	`True`	—	عدد محاولات التنفيذ المسجلة لتدفق المصدر هذا.
`failure_code`	`str \| None`	`True`	—	رمز فشل تقرؤه الآلة، وقد يكون فارغاً؛ حوّله إلى نص مستخدم مترجم.
`failure_class`	`str \| None`	`True`	—	تصنيف فشل تقرؤه الآلة وقد يكون فارغاً، وهو منفصل عن failure_code.
`runnable_at`	`str \| None`	`True`	—	وقت تأهل هذا التدفق للتنفيذ وقد يكون فارغاً.

`ContentPreparation`

حالات التحضير المعتمد هي awaiting_client وpreparing وhashing وuploading وawaiting_retry وready وabandoned وnot_required. قد تكون attempt_id ومواعيد انتهاء الحجز والرفع فارغة. تحتوي allowed_actions الإجراءات المؤهلة حالياً فقط: start_preparation أوretry_preparation أوabandon_source. تتطلب الإعادة attempt_id السابقة وUUID جديداً؛ لا تعد تزويد العمل الجاهز أو النهائي دون تحقق.

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`state`	`str`	`True`	—	حالة هذا السجل؛ يميّز شرح المخطط الحاوي حالات التحضير من حالات العملية.
`attempt_id`	`str \| None`	`True`	—	قيمة UUID جديدة يختارها المستدعي وتؤكدها استجابة التحضير؛ استخدمها في كل طلب يخص هذه المحاولة.
`attempt_number`	`int`	`True`	—	مراجعة محاولة التحضير أو رمز الفشل أو وقت الانتهاء؛ تتطلب المحاولات أو الأهداف المنتهية استرداداً معتمداً.
`client_progress_revision`	`int`	`True`	—	رقم مراجعة متزايد للتقدم المقبول من العميل داخل المحاولة الحالية.
`failure_code`	`str \| None`	`True`	—	رمز فشل تقرؤه الآلة، وقد يكون فارغاً؛ حوّله إلى نص مستخدم مترجم.
`updated_at`	`str \| None`	`True`	—	وقت مسجل لدى الخادم؛ تشير القيمة الفارغة إلى أن الحدث لم يقع أو أن الوقت غير متاح.
`lease_expires_at`	`str \| None`	`True`	—	وقت انتهاء ISO لحجز التحضير أو هدف الرفع الصادر، وقد يكون فارغاً.
`upload_expires_at`	`str \| None`	`True`	—	وقت انتهاء ISO لحجز التحضير أو هدف الرفع الصادر، وقد يكون فارغاً.
`allowed_actions`	`tuple[str, ...]`	`True`	—	الإجراءات المسموح بها حالياً في الحالة المعتمدة، وليست ضماناً للطلبات اللاحقة.

`ContentPreparationResponse`

هذه لقطة التحضير المتداخلة وليست execution_state للعملية. تغلفها نقطة نهاية التحضير مع operation_id وcontent_id وprogress. تكون state هي preparing بعد قبول البدء أو الإعادة؛ تحقق من attempt_id المؤكدة. تأتي media_id من المسار أوsource_ref_map وليس هذا الغلاف.

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`state`	`Literal['awaiting_client', 'preparing', 'hashing', 'uploading', 'awaiting_retry', 'ready', 'abandoned', 'not_required']`	`True`	—	حالة هذا السجل؛ يميّز شرح المخطط الحاوي حالات التحضير من حالات العملية.
`attempt_id`	`str \| None`	`False`	`None`	قيمة UUID جديدة يختارها المستدعي وتؤكدها استجابة التحضير؛ استخدمها في كل طلب يخص هذه المحاولة.
`attempt_number`	`int`	`True`	—	مراجعة محاولة التحضير أو رمز الفشل أو وقت الانتهاء؛ تتطلب المحاولات أو الأهداف المنتهية استرداداً معتمداً.
`client_progress_revision`	`int`	`True`	—	رقم مراجعة متزايد للتقدم المقبول من العميل داخل المحاولة الحالية.
`failure_code`	`str \| None`	`False`	`None`	رمز فشل تقرؤه الآلة، وقد يكون فارغاً؛ حوّله إلى نص مستخدم مترجم.
`updated_at`	`str \| None`	`False`	`None`	وقت مسجل لدى الخادم؛ تشير القيمة الفارغة إلى أن الحدث لم يقع أو أن الوقت غير متاح.
`lease_expires_at`	`str \| None`	`False`	`None`	وقت انتهاء ISO لحجز التحضير أو هدف الرفع الصادر، وقد يكون فارغاً.
`upload_expires_at`	`str \| None`	`False`	`None`	وقت انتهاء ISO لحجز التحضير أو هدف الرفع الصادر، وقد يكون فارغاً.
`allowed_actions`	`list[Literal['start_preparation', 'retry_preparation', 'abandon_source']]`	`True`	—	الإجراءات المسموح بها حالياً في الحالة المعتمدة، وليست ضماناً للطلبات اللاحقة.

`ContentProgress`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`version`	`int`	`True`	—	إصدار مخطط التقدم وهو 4 حالياً؛ ارفض الإصدارات غير المدعومة بدلاً من تخمين بنيتها.
`revision`	`int`	`True`	—	رقم مراجعة متزايد للتقدم المعتمد؛ طابق الأحداث القديمة مع حالة HTTP.
`status`	`ProgressStatus`	`True`	—	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`phase_plan`	`tuple[str, ...]`	`True`	—	مراحل مرتبة في سير العمل المقبول؛ المراحل الغائبة لا تعني عملاً ضمنياً.
`current_phase`	`str \| None`	`True`	—	المرحلة أو الخطوة النشطة وقد تكون فارغة. قد لا تتضمن اللقطة النهائية مرحلة أو خطوة نشطة.
`current_step_name`	`str \| None`	`True`	—	خطوة تنفيذ تقرؤها الآلة؛ استخدم نوع التدفق أو التقدم الحاوي وقيمه المعدودة.
`active_work_units`	`int`	`True`	—	عدد وحدات العمل النشطة حالياً في هذه الخطوة أو المرحلة أو اللقطة.
`counts`	`Mapping[str, int]`	`True`	—	أعداد مراحل متداخلة: الكلية والمحسومة والمكتملة والمتجاوزة والفاشلة.
`phases`	`Mapping[str, ProgressPhase]`	`True`	—	سجلات مراحل أو خطوات متداخلة بمفتاح قيمة التعداد المقابلة؛ افحص حالتها وقياساتها.

`CreditEstimate`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`required_credits`	`int`	`True`	—	عرض الرصيد أو قرار قبول من التقدير الحالي؛ راجع نوع الحقل الحاوي.
`available_credits`	`int`	`True`	—	عرض الرصيد أو قرار قبول من التقدير الحالي؛ راجع نوع الحقل الحاوي.
`shortfall`	`int`	`True`	—	عرض الرصيد أو قرار قبول من التقدير الحالي؛ راجع نوع الحقل الحاوي.
`missing_metrics`	`int`	`True`	—	عدد مقاييس المصدر المطلوبة الغائبة؛ يجب أن يكون صفراً قبل الاعتماد.
`can_commit`	`bool`	`True`	—	عرض الرصيد أو قرار قبول من التقدير الحالي؛ راجع نوع الحقل الحاوي.
`contents`	`tuple[CreditEstimateContent, ...]`	`True`	—	عناصر مصدر متداخلة أو صفوف تقدير لكل مصدر وفق السجل الحاوي.

`CreditEstimateContent`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`source_ref`	`SourceRef`	`True`	—	زوج ثابت من معرّف وسائط المشروع ومعرّف الأصل المختار؛ تختلف عنه معرّفات عناصر المصدر أثناء التنفيذ.
`media_path`	`str`	`True`	—	العلاقة بين وسائط العملية والمشروع مع مسار الوسائط النسبي المسجل.
`type`	`ContentType`	`True`	—	فئة المصدر text أوaudio أوgraphical؛ تحدد المقاييس والمراحل المطلوبة.
`stream_class`	`str`	`True`	—	التصنيف العادي أو أي مجموعة من التعليق والإجباري وSDH.
`stream_index`	`int \| None`	`True`	—	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.
`character_count`	`int \| None`	`True`	—	محارف مرئية أو صور رسومية مقاسة تطلبها الخطة؛ لا تستبدلها بأعداد مخمّنة.
`image_count`	`int \| None`	`True`	—	محارف مرئية أو صور رسومية مقاسة تطلبها الخطة؛ لا تستبدلها بأعداد مخمّنة.
`duration_seconds`	`float \| None`	`True`	—	المدة المقاسة بالثواني، وليست وقت معالجة مضموناً.
`credits`	`int \| None`	`True`	—	الرصيد المقدّر لهذا المصدر.

`EffectiveMetadata`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`language`	`str`	`False`	`Field(default='und', max_length=32)`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`classification`	`tuple[Disposition, ...] \| None`	`False`	`Field(default=None, max_length=16)`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.

`ExportOptions`

`FileObservation`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`role`	`Literal['primary', 'index', 'data']`	`False`	`'primary'`	دور الملف الفعلي أو بصمته المرصودة أو وصف المسار المستخدم للفحوص المحمية.
`size_bytes`	`StrictInt`	`True`	`Field(ge=0)`	حجم الملف أو النقل الفعلي أو تقدم البايتات المقاس.
`last_modified_ms`	`StrictInt`	`True`	—	وقت تعديل الملف الذي تمت ملاحظته بالمللي ثانية.
`sampled_fingerprint`	`str \| None`	`False`	`Field(default=None, max_length=128)`	دور الملف الفعلي أو بصمته المرصودة أو وصف المسار المستخدم للفحوص المحمية.

`OperationBaseResponse`

execution_state هي pending أوrunning أوfinished. تبقى outcome فارغة حتى finished ثم تكون succeeded أوpartially_succeeded أوfailed أوcanceled. display_status هي الحالة أو النتيجة النهائية. تلخص الأعداد المحتوى المفعّل؛ ترتب state_version وevent_sequence الملاحظات. لكل عملية committed_at وcharged_credits؛ لا تكلفة للخطط المؤقتة. تبقى media مفتوحة في تصريح الاستجابة؛ تصف سجلات المحلل أدناه الحقول المتداخلة المستخدمة.

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`operation_id`	`str`	`True`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`project_id`	`str \| None`	`False`	`None`	معرّف المشروع المحفوظ، كما تعيده عملية إنشاء المشروع أو قائمة المشاريع.
`kind`	`str`	`True`	—	محدد خاص بنقطة النهاية لنوع الأصل أو نطاق الفحص أو الجاهزية أو الموضع؛ اتبع عقد نقطة النهاية.
`target_language`	`str \| None`	`False`	`None`	رمز اللغة الهدف للترجمة النصية المولدة أو المترجمة.
`execution_state`	`Literal['pending', 'running', 'finished']`	`True`	—	حقل دورة حياة معتمد: التنفيذ أو النتيجة النهائية أو العرض أو رقم مراجعة وتسلسل متزايد.
`outcome`	`Literal['succeeded', 'partially_succeeded', 'failed', 'canceled'] \| None`	`True`	—	حقل دورة حياة معتمد: التنفيذ أو النتيجة النهائية أو العرض أو رقم مراجعة وتسلسل متزايد.
`display_status`	`Literal['pending', 'running', 'succeeded', 'partially_succeeded', 'failed', 'canceled']`	`True`	—	حقل دورة حياة معتمد: التنفيذ أو النتيجة النهائية أو العرض أو رقم مراجعة وتسلسل متزايد.
`state_version`	`int`	`True`	—	حقل دورة حياة معتمد: التنفيذ أو النتيجة النهائية أو العرض أو رقم مراجعة وتسلسل متزايد.
`event_sequence`	`int`	`True`	—	حقل دورة حياة معتمد: التنفيذ أو النتيجة النهائية أو العرض أو رقم مراجعة وتسلسل متزايد.
`phase_counts`	`WorkflowPhaseCounts`	`True`	—	إسقاطات سير عمل وأعداد متداخلة؛ راجع المخطط المسمى بدلاً من اعتبارها نص حالة.
`content_counts`	`OperationLifecycleContentCountsResponse`	`True`	—	إسقاطات سير عمل وأعداد متداخلة؛ راجع المخطط المسمى بدلاً من اعتبارها نص حالة.
`preparation_counts`	`OperationPreparationCountsResponse`	`True`	—	إسقاطات سير عمل وأعداد متداخلة؛ راجع المخطط المسمى بدلاً من اعتبارها نص حالة.
`allowed_actions`	`list[Literal['abort']]`	`True`	—	الإجراءات المسموح بها حالياً في الحالة المعتمدة، وليست ضماناً للطلبات اللاحقة.
`started_at`	`str \| None`	`False`	`None`	وقت مسجل لدى الخادم؛ تشير القيمة الفارغة إلى أن الحدث لم يقع أو أن الوقت غير متاح.
`finished_at`	`str \| None`	`False`	`None`	وقت مسجل لدى الخادم؛ تشير القيمة الفارغة إلى أن الحدث لم يقع أو أن الوقت غير متاح.
`updated_at`	`str \| None`	`False`	`None`	وقت مسجل لدى الخادم؛ تشير القيمة الفارغة إلى أن الحدث لم يقع أو أن الوقت غير متاح.
`created_at`	`str \| None`	`False`	`None`	وقت مسجل لدى الخادم؛ تشير القيمة الفارغة إلى أن الحدث لم يقع أو أن الوقت غير متاح.
`committed_at`	`str`	`True`	—	وقت إلزامي يسجله الخادم عند اعتماد العملية.
`charged_credits`	`int`	`True`	—	الرصيد المخصوم عند بدء العمل.
`charged_at`	`str \| None`	`False`	`None`	وقت مسجل لدى الخادم؛ تشير القيمة الفارغة إلى أن الحدث لم يقع أو أن الوقت غير متاح.
`refunded_credits`	`int`	`True`	—	الرصيد المعاد لاحقًا مقابل المراحل أو المصادر المستحقة للاسترداد.
`used_credits`	`int`	`True`	—	الرصيد المخصوم مطروحًا منه الرصيد المعاد، على ألا تقل النتيجة عن صفر.
`workflow`	`OperationWorkflowSummaryResponse`	`False`	`Field(default_factory=OperationWorkflowSummaryResponse)`	إسقاطات سير عمل وأعداد متداخلة؛ راجع المخطط المسمى بدلاً من اعتبارها نص حالة.

`OperationContent`

عنصر مصدر متداخل كما يطبّعه محلل CLI. تحتوي source_ref على media_id للمشروع وasset_id. تحمل asset_input.selection قيم تحقق AssetSelection الصادرة عن الخادم دون تغيير. يُوصف preparation أدناه؛ قد يكون flow فارغاً. progress بالإصدار 4 وليس نسبة اكتمال. تصف أنواع الفراغ والاختيارية هنا القيم المطبّعة وليست نموذج تحقق HTTP شاملاً.

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`source_ref`	`SourceRef`	`True`	—	زوج ثابت من معرّف وسائط المشروع ومعرّف الأصل المختار؛ تختلف عنه معرّفات عناصر المصدر أثناء التنفيذ.
`enabled`	`bool`	`True`	—	تضمين المصدر أو تجاوز لغته صراحةً في الخطة الحالية.
`type`	`ContentType`	`True`	—	فئة المصدر text أوaudio أوgraphical؛ تحدد المقاييس والمراحل المطلوبة.
`stream_class`	`str`	`True`	—	التصنيف العادي أو أي مجموعة من التعليق والإجباري وSDH.
`codec_type`	`str \| None`	`True`	—	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`codec_name`	`str \| None`	`True`	—	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`stream_index`	`int \| None`	`True`	—	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.
`filename`	`str \| None`	`True`	—	اسم الملف المحضّر مع امتداده الفعلي، لتحديد تنسيق التخزين.
`language`	`str \| None`	`True`	—	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`language_override`	`str \| None`	`True`	—	تضمين المصدر أو تجاوز لغته صراحةً في الخطة الحالية.
`workflow_kind`	`str \| None`	`True`	—	سير المراحل المختار وشرح التخطيط له؛ فارغ عند عدم اختيار سير عمل.
`workflow_reason`	`str \| None`	`True`	—	سير المراحل المختار وشرح التخطيط له؛ فارغ عند عدم اختيار سير عمل.
`input_snapshot_id`	`str \| None`	`True`	—	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`asset_input`	`dict[str, Any]`	`True`	—	عقد مدخل صادر عن الخادم؛ احتفظ بقيم تحقق الاختيار وهوية الأصل.
`id`	`str`	`True`	—	معرّف المورد المعاد.
`status`	`str`	`True`	—	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`preparation`	`ContentPreparation`	`True`	—	لقطة محاولة معتمدة تتضمن الحالة وقيمة تحقق المحاولة والإجراءات المسموحة.
`flow`	`ContentFlow \| None`	`True`	—	حالة تدفق معتمدة تقبل الفراغ: status وstep وexecution_count وfailure_code وfailure_class وrunnable_at.
`failure_code`	`str \| None`	`True`	—	رمز فشل تقرؤه الآلة، وقد يكون فارغاً؛ حوّله إلى نص مستخدم مترجم.
`progress_updated_at`	`str \| None`	`True`	—	وقت آخر تحديث تقدم مقبول، وقد يكون فارغاً.
`progress`	`ContentProgress`	`True`	—	تقدم بالإصدار 4 مع phase_plan والمرحلة والخطوة والقياس الحالي وphases وrevision. ليس قيمة نسبة قديمة.

`OperationLifecycleContentCountsResponse`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`total`	`int`	`True`	—	مرحلة التقدم المحلي وعدد العناصر أو البايتات المكتملة المقاس؛ الاستدعاءات متزامنة.
`pending`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`uploading`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`processing`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`completed`	`int`	`True`	—	وحدات القياس المكتملة من 0 إلى total. لا يمكن أن يتجاوز القياس مجموعه.
`failed`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`skipped`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`terminal`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.

`OperationMedia`

وسائط عملية متداخلة. id هو معرّف التشغيل وproject_media_id وجهتها الدائمة في المشروع. contents مصفوفة JSON في النقل وtuple في سجل محلل CLI. لا تزوّد العناصر المعطّلة.

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`id`	`str`	`True`	—	معرّف المورد المعاد.
`project_media_id`	`str`	`True`	—	العلاقة بين وسائط العملية والمشروع مع مسار الوسائط النسبي المسجل.
`path`	`str`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`enabled`	`bool`	`True`	—	تضمين المصدر أو تجاوز لغته صراحةً في الخطة الحالية.
`contents`	`tuple[OperationContent, ...]`	`True`	—	عناصر مصدر متداخلة أو صفوف تقدير لكل مصدر وفق السجل الحاوي.

`OperationPreparationCountsResponse`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`awaiting_client`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`preparing`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`hashing`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`uploading`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`awaiting_retry`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`ready`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`abandoned`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.
`not_required`	`int`	`True`	—	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.

`OperationResultExportResponse`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`artifact_id`	`str`	`True`	—	معرّف ناتج مرحلة ناجحة وثابتة، كما تعيده قائمة النتائج.
`snapshot_id`	`str`	`True`	—	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`content_id`	`str`	`True`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`output_target`	`OutputTarget`	`True`	—	external_srt أو external_vtt أو external_ass أو embedded؛ تستخدم None افتراض نقطة النهاية أو الحساب.
`capture`	`CapturedExport`	`True`	—	بيانات تصدير ثابتة أو اسم ملف نسبي مقترح من الخادم أو نص الترجمة المتسلسل الفعلي.
`suggested_path`	`str`	`True`	—	بيانات تصدير ثابتة أو اسم ملف نسبي مقترح من الخادم أو نص الترجمة المتسلسل الفعلي.
`mime_type`	`str`	`True`	—	نوع MIME المكتشف؛ لا يثبت وحده دعم الترميز.
`text_content`	`str`	`True`	—	بيانات تصدير ثابتة أو اسم ملف نسبي مقترح من الخادم أو نص الترجمة المتسلسل الفعلي.
`media_path`	`str`	`True`	—	العلاقة بين وسائط العملية والمشروع مع مسار الوسائط النسبي المسجل.
`language`	`str \| None`	`False`	`None`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`stream_index`	`int \| None`	`False`	`None`	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.
`stream_class`	`str \| None`	`False`	`None`	التصنيف العادي أو أي مجموعة من التعليق والإجباري وSDH.

`OperationWorkflowSummaryResponse`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`requested`	`WorkflowStageFlagsResponse`	`False`	`Field(default_factory=WorkflowStageFlagsResponse)`	علامات مراحل متداخلة: audio_transcription وocr_transcription وtranslation. ميّز الخطة المطلوبة عن المراحل اللازمة بعد تخطي المراحل التي لم تبدأ عند التسوية.
`needed`	`WorkflowStageFlagsResponse`	`False`	`Field(default_factory=WorkflowStageFlagsResponse)`	علامات مراحل متداخلة: audio_transcription وocr_transcription وtranslation. ميّز الخطة المطلوبة عن المراحل اللازمة بعد تخطي المراحل التي لم تبدأ عند التسوية.
`skipped`	`WorkflowStageFlagsResponse`	`False`	`Field(default_factory=WorkflowStageFlagsResponse)`	عدد المصادر في حالة دورة الحياة أو التحضير المسماة؛ الأعداد ليست نسباً مئوية.

`ProgressMeasurement`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`completed`	`Annotated[int, Field(ge=0, le=2 ** 63 - 1)]`	`True`	—	وحدات القياس المكتملة من 0 إلى total. لا يمكن أن يتجاوز القياس مجموعه.
`total`	`Annotated[int, Field(gt=0, le=2 ** 63 - 1)]`	`True`	—	مرحلة التقدم المحلي وعدد العناصر أو البايتات المكتملة المقاس؛ الاستدعاءات متزامنة.
`unit`	`ProgressUnit`	`True`	—	وحدة قياس من ProgressUnit البايتات أو العناصر أو المقاطع أو المللي ثانية؛ استخدم قيم التعداد المعلنة.

`ProgressMeasurementSnapshot`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`completed`	`int`	`True`	—	وحدات القياس المكتملة من 0 إلى total. لا يمكن أن يتجاوز القياس مجموعه.
`total`	`int`	`True`	—	مرحلة التقدم المحلي وعدد العناصر أو البايتات المكتملة المقاس؛ الاستدعاءات متزامنة.
`unit`	`str`	`True`	—	وحدة قياس من ProgressUnit البايتات أو العناصر أو المقاطع أو المللي ثانية؛ استخدم قيم التعداد المعلنة.
`percent`	`float`	`True`	`Field(ge=0, le=100)`	مرحلة التقدم المحلي وعدد العناصر أو البايتات المكتملة المقاس؛ الاستدعاءات متزامنة.

`ProgressPhase`

JSON

{
  "PREPARATION": "preparation",
  "UPLOADING": "uploading",
  "TRANSCRIPTION": "transcription",
  "TRANSLATION": "translation"
}

`ProgressPhaseSnapshot`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`status`	`ProgressStatus`	`False`	`ProgressStatus.PENDING`	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`current_step`	`ProgressStep \| None`	`False`	`None`	المرحلة أو الخطوة النشطة وقد تكون فارغة. قد لا تتضمن اللقطة النهائية مرحلة أو خطوة نشطة.
`measurement`	`ProgressMeasurementSnapshot \| None`	`False`	`None`	قياس completed وtotal وunit للعمل الفعلي وقد يكون فارغاً، مع percent في اللقطات فقط.
`active_work_units`	`int`	`False`	`Field(default=0, ge=0)`	عدد وحدات العمل النشطة حالياً في هذه الخطوة أو المرحلة أو اللقطة.
`steps`	`dict[ProgressStep, ProgressStepSnapshot]`	`True`	—	سجلات مراحل أو خطوات متداخلة بمفتاح قيمة التعداد المقابلة؛ افحص حالتها وقياساتها.

`ProgressSnapshotV4`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`version`	`Literal[4]`	`False`	`PROGRESS_SCHEMA_VERSION`	إصدار مخطط التقدم وهو 4 حالياً؛ ارفض الإصدارات غير المدعومة بدلاً من تخمين بنيتها.
`revision`	`int`	`False`	`Field(default=0, ge=0)`	رقم مراجعة متزايد للتقدم المعتمد؛ طابق الأحداث القديمة مع حالة HTTP.
`status`	`ProgressStatus`	`False`	`ProgressStatus.PENDING`	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`phase_plan`	`list[ProgressPhase]`	`True`	—	مراحل مرتبة في سير العمل المقبول؛ المراحل الغائبة لا تعني عملاً ضمنياً.
`counts`	`WorkflowPhaseCounts`	`True`	—	أعداد مراحل متداخلة: الكلية والمحسومة والمكتملة والمتجاوزة والفاشلة.
`current_phase`	`ProgressPhase \| None`	`False`	`None`	المرحلة أو الخطوة النشطة وقد تكون فارغة. قد لا تتضمن اللقطة النهائية مرحلة أو خطوة نشطة.
`current_step`	`ProgressStep \| None`	`False`	`None`	المرحلة أو الخطوة النشطة وقد تكون فارغة. قد لا تتضمن اللقطة النهائية مرحلة أو خطوة نشطة.
`measurement`	`ProgressMeasurementSnapshot \| None`	`False`	`None`	قياس completed وtotal وunit للعمل الفعلي وقد يكون فارغاً، مع percent في اللقطات فقط.
`active_work_units`	`int`	`False`	`Field(default=0, ge=0)`	عدد وحدات العمل النشطة حالياً في هذه الخطوة أو المرحلة أو اللقطة.
`phases`	`dict[ProgressPhase, ProgressPhaseSnapshot]`	`True`	—	سجلات مراحل أو خطوات متداخلة بمفتاح قيمة التعداد المقابلة؛ افحص حالتها وقياساتها.

`ProgressStatus`

JSON

{
  "PENDING": "pending",
  "RUNNING": "running",
  "COMPLETED": "completed",
  "SKIPPED": "skipped",
  "FAILED": "failed"
}

`ProgressStep`

JSON

{
  "EXTRACTING_STREAM": "extracting_stream",
  "HASHING_SOURCE": "hashing_source",
  "UPLOADING_SOURCE": "uploading_source",
  "DOWNLOADING_SOURCE": "downloading_source",
  "STARTING_RUNTIME": "starting_runtime",
  "RESOLVING_MODEL": "resolving_model",
  "LOADING_TOKENIZER": "loading_tokenizer",
  "LOADING_MODEL": "loading_model",
  "LOADING_INPUT": "loading_input",
  "RUNNING_INFERENCE": "running_inference",
  "ALIGNING_TIMESTAMPS": "aligning_timestamps",
  "EXTRACTING_SUBTITLE_TRACK": "extracting_subtitle_track",
  "RUNNING_OCR": "running_ocr",
  "PARSING_OCR_OUTPUT": "parsing_ocr_output",
  "FINALIZING_RESULT": "finalizing_result"
}

`ProgressStepSnapshot`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`status`	`ProgressStatus`	`False`	`ProgressStatus.PENDING`	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`measurement`	`ProgressMeasurementSnapshot \| None`	`False`	`None`	قياس completed وtotal وunit للعمل الفعلي وقد يكون فارغاً، مع percent في اللقطات فقط.
`active_work_units`	`int`	`False`	`Field(default=0, ge=0)`	عدد وحدات العمل النشطة حالياً في هذه الخطوة أو المرحلة أو اللقطة.
`started_at`	`datetime \| None`	`False`	`None`	وقت مسجل لدى الخادم؛ تشير القيمة الفارغة إلى أن الحدث لم يقع أو أن الوقت غير متاح.

`ProgressUnit`

JSON

{
  "BYTES": "bytes",
  "ITEMS": "items",
  "CHUNKS": "chunks",
  "MILLISECONDS": "milliseconds"
}

`ProgressUpdateV4`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`version`	`Literal[4]`	`False`	`PROGRESS_SCHEMA_VERSION`	إصدار مخطط التقدم وهو 4 حالياً؛ ارفض الإصدارات غير المدعومة بدلاً من تخمين بنيتها.
`phase`	`ProgressPhase`	`True`	—	مرحلة التقدم المحلي وعدد العناصر أو البايتات المكتملة المقاس؛ الاستدعاءات متزامنة.
`step`	`ProgressStep`	`True`	—	خطوة تنفيذ تقرؤها الآلة؛ استخدم نوع التدفق أو التقدم الحاوي وقيمه المعدودة.
`status`	`ProgressStatus`	`True`	—	مرشح الحالة أو الحالة الجديدة وفقاً للدالة؛ تحتفظ المشاريع المؤرشفة بالنتائج المحفوظة.
`work_unit_id`	`Annotated[str, Field(min_length=1, max_length=255)]`	`True`	—	هوية وحدة العمل المقاسة هذه؛ احتفظ بها عبر تحديثات التقدم المتزايدة.
`sequence`	`Annotated[int, Field(ge=0, le=2 ** 63 - 1)]`	`True`	—	تسلسل تحديث متزايد داخل وحدة عمل واحدة؛ لا تستبدل الحالة الأحدث بتحديثات قديمة.
`measurement`	`ProgressMeasurement \| None`	`False`	`None`	قياس completed وtotal وunit للعمل الفعلي وقد يكون فارغاً، مع percent في اللقطات فقط.

`ProjectOperationCommitRequest`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`media_ids`	`list[Annotated[str, Field(max_length=64)]]`	`True`	`Field(min_length=1, max_length=OPERATION_MEDIA_MAX_COUNT)`	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.
`target_language`	`str`	`True`	`Field(min_length=1, max_length=32)`	رمز اللغة الهدف للترجمة النصية المولدة أو المترجمة.
`content_overrides`	`list[ProjectOperationContentOverride]`	`False`	`Field(default_factory=list, max_length=OPERATION_MEDIA_MAX_COUNT * 4)`	تجاوزات مرتبطة بمرجع source_ref ثابت: تفعيل المصدر أو تحديد لغته صراحةً.
`metrics`	`list[ProjectOperationMetricEntry]`	`False`	`Field(default_factory=list, max_length=OPERATION_MEDIA_MAX_COUNT * 4)`	مقاييس المصدر التي تطلبها الخطة الحالية فقط، محسوبة محلياً. مدة الصوت موجودة بالفعل في الجرد المفحوص.
`source_selections`	`list[AssetSelection]`	`True`	`Field(max_length=OPERATION_MEDIA_MAX_COUNT * 4)`	اختيارات محمية من الخطة المقدّرة مع source_language الموحّدة؛ احتفظ باللقطات والملاحظات.

`ProjectOperationCommitResponse`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`operation`	`dict[str, Any]`	`True`	—	كائن الخطة أو التقدير أو الاعتماد أو خريطة المصادر المحمية. تبقى بيانات dict[str, Any] مفتوحة؛ يتحقق المثال من الحقول المستخدمة.
`commit`	`dict[str, Any]`	`True`	—	كائن الخطة أو التقدير أو الاعتماد أو خريطة المصادر المحمية. تبقى بيانات dict[str, Any] مفتوحة؛ يتحقق المثال من الحقول المستخدمة.
`source_ref_map`	`dict[str, dict[str, str]]`	`True`	—	كائن الخطة أو التقدير أو الاعتماد أو خريطة المصادر المحمية. تبقى بيانات dict[str, Any] مفتوحة؛ يتحقق المثال من الحقول المستخدمة.

`ProjectOperationContentOverride`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`source_ref`	`ProjectOperationSourceRef`	`True`	—	زوج ثابت من معرّف وسائط المشروع ومعرّف الأصل المختار؛ تختلف عنه معرّفات عناصر المصدر أثناء التنفيذ.
`enabled`	`bool \| None`	`False`	`None`	تضمين المصدر أو تجاوز لغته صراحةً في الخطة الحالية.
`language_override`	`str \| None`	`False`	`Field(default=None, max_length=32)`	تضمين المصدر أو تجاوز لغته صراحةً في الخطة الحالية.

`ProjectOperationMetricEntry`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`source_ref`	`ProjectOperationSourceRef`	`True`	—	زوج ثابت من معرّف وسائط المشروع ومعرّف الأصل المختار؛ تختلف عنه معرّفات عناصر المصدر أثناء التنفيذ.
`duration_seconds`	`float \| int \| None`	`False`	`None`	المدة المقاسة بالثواني، وليست وقت معالجة مضموناً.
`image_count`	`int \| None`	`False`	`None`	محارف مرئية أو صور رسومية مقاسة تطلبها الخطة؛ لا تستبدلها بأعداد مخمّنة.

`ProjectOperationPlanContentResponse`

عقد مستمد من المصدر. احتفظ بالحقول المطلوبة والضوابط عند تعديل الوصفة؛ القيم القابلة للفراغ تختلف عن الحقول المطلوبة المفقودة.

الحقل	النوع	مطلوب	التصريح / الافتراضي	المعنى
`source_ref`	`ProjectOperationSourceRef`	`True`	—	زوج ثابت من معرّف وسائط المشروع ومعرّف الأصل المختار؛ تختلف عنه معرّفات عناصر المصدر أثناء التنفيذ.
`source_asset_id`	`str \| None`	`True`	—	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`enabled`	`bool`	`True`	—	تضمين المصدر أو تجاوز لغته صراحةً في الخطة الحالية.
`sparse_normal`	`bool`	`True`	—	يقترح فحص تصنيف الترجمة النصية العادية تلقائيًا عندما تكون أسطرها المعروفة قليلة مقارنة بطول الوسائط.
`language`	`str`	`True`	—	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`language_mode`	`str \| None`	`True`	—	أدلة لغة المصدر التي يستخدمها المخطط؛ تبقى رموز اللغات بصيغتها المعيارية.
`language_source`	`str \| None`	`True`	—	أدلة لغة المصدر التي يستخدمها المخطط؛ تبقى رموز اللغات بصيغتها المعيارية.
`language_declared`	`str \| None`	`True`	—	أدلة لغة المصدر التي يستخدمها المخطط؛ تبقى رموز اللغات بصيغتها المعيارية.
`language_declared_source`	`str \| None`	`True`	—	أدلة لغة المصدر التي يستخدمها المخطط؛ تبقى رموز اللغات بصيغتها المعيارية.
`language_guess`	`str \| None`	`True`	—	أدلة لغة المصدر التي يستخدمها المخطط؛ تبقى رموز اللغات بصيغتها المعيارية.
`language_guess_source`	`str \| None`	`True`	—	أدلة لغة المصدر التي يستخدمها المخطط؛ تبقى رموز اللغات بصيغتها المعيارية.
`language_override`	`str \| None`	`True`	—	تضمين المصدر أو تجاوز لغته صراحةً في الخطة الحالية.
`language_guess_status`	`str \| None`	`True`	—	حالة جاهزية اكتشاف لغة المصدر قبل تأكيد التنفيذ.
`language_guess_confidence`	`float \| None`	`True`	—	درجة الثقة في تخمين لغة المصدر.
`language_profile`	`dict[str, Any] \| None`	`True`	—	ملف لغة المصدر المرفق بأدلة اللغة.
`type`	`str \| None`	`True`	—	فئة المصدر text أوaudio أوgraphical؛ تحدد المقاييس والمراحل المطلوبة.
`stream_type`	`str \| None`	`True`	—	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`stream_class`	`str \| None`	`True`	—	التصنيف العادي أو أي مجموعة من التعليق والإجباري وSDH.
`codec_type`	`str \| None`	`True`	—	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`codec_name`	`str \| None`	`True`	—	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`filename`	`str \| None`	`True`	—	اسم الملف المحضّر مع امتداده الفعلي، لتحديد تنسيق التخزين.
`input_snapshot_id`	`str \| None`	`True`	—	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`stream_index`	`int \| None`	`True`	—	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.
`asset_input`	`dict[str, Any] \| None`	`True`	—	عقد مدخل صادر عن الخادم؛ احتفظ بقيم تحقق الاختيار وهوية الأصل.
`workflow_kind`	`str`	`True`	—	سير المراحل المختار وشرح التخطيط له؛ فارغ عند عدم اختيار سير عمل.
`workflow_reason`	`str`	`True`	—	سير المراحل المختار وشرح التخطيط له؛ فارغ عند عدم اختيار سير عمل.
`needs_audio_transcription`	`bool`	`True`	—	ما إذا كان هذا المصدر يحتاج إلى مرحلة المعالجة المذكورة.
`needs_ocr_transcription`	`bool`	`True`	—	ما إذا كان هذا المصدر يحتاج إلى مرحلة المعالجة المذكورة.
`needs_translation`	`bool`	`True`	—	ما إذا كان هذا المصدر يحتاج إلى مرحلة المعالجة المذكورة.
`translation_decision`	`str`	`True`	—	ما إذا كانت الخطة تتطلب الترجمة أو تتجاوزها.
`audio_transcription_engine`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`audio_transcription_app`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`audio_transcription_model`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`audio_transcription_model_mode`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`audio_transcription_route_reason`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`audio_transcription_route_rule`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`ocr_engine`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`ocr_model`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`translation_provider`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`translation_model`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`translation_model_mode`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`translation_route_reason`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`translation_route_rule`	`str \| None`	`True`	—	مسار المعالجة أو النموذج الذي اختاره الخادم أو أدلة اختيار هذه المرحلة.
`estimated_character_count`	`int \| None`	`True`	—	حجم العمل التقديري المقاس للمصدر المحدد.
`estimated_cue_count`	`int \| None`	`True`	—	العدد التقديري للمقاطع النصية المرئية في اللقطة المحددة.
`estimated_image_count`	`int \| None`	`True`	—	حجم العمل التقديري المقاس للمصدر المحدد.
`estimated_duration_seconds`	`int \| None`	`True`	—	حجم العمل التقديري المقاس للمصدر المحدد.
`estimated_credits`	`int \| None`	`True`	—	الرصيد المقدّر لهذا المصدر أو لمرحلة المعالجة المذكورة.
`estimated_audio_transcription_credits`	`int \| None`	`True`	—	الرصيد المقدّر لهذا المصدر أو لمرحلة المعالجة المذكورة.
`estimated_ocr_transcription_credits`	`int \| None`	`True`	—	الرصيد المقدّر لهذا المصدر أو لمرحلة المعالجة المذكورة.
`estimated_translation_credits`	`int \| None`	`True`	—	الرصيد المقدّر لهذا المصدر أو لمرحلة المعالجة المذكورة.

`ProjectOperationPlanSlotResponse`

الحقل	النوع	مطلوب	التصريح / الافتراضي	المعنى
`slot`	`str`	`True`	—	تصنيف النتيجة: normal أو forced أو sdh أو commentary أو مزيج منها.
`source_asset_id`	`str`	`True`	—	معرّف أصل المصدر الموصى به لهذه النتيجة، ويُحسب قبل تعديلات المستخدم.
`available`	`bool`	`True`	—	ما إذا كان نص ذو تحديد موثوق للغة موجودًا بالفعل باللغة المستهدفة لهذه النتيجة.

`ProjectOperationPlanMediaResponse`

الحقل	النوع	مطلوب	التصريح / الافتراضي	المعنى
`project_media_id`	`str`	`True`	—	العلاقة بين وسائط العملية والمشروع مع مسار الوسائط النسبي المسجل.
`path`	`str`	`True`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.
`probe_data`	`dict[str, Any] \| None`	`True`	—	أدلة الحاوية والمسارات الفعلية من FFprobe؛ تحتفظ الخرائط المفتوحة بحقول الفحص.
`contents`	`list[ProjectOperationPlanContentResponse]`	`True`	—	عناصر مصدر متداخلة أو صفوف تقدير لكل مصدر وفق السجل الحاوي.
`slots`	`list[ProjectOperationPlanSlotResponse]`	`True`	—	النتائج التي لها مصدر مرشح، مع المصدر الموصى به وحالة التوفر.

`ProjectOperationPlanPayload`

الحقل	النوع	مطلوب	التصريح / الافتراضي	المعنى
`target_language`	`str`	`True`	—	رمز اللغة الهدف للترجمة النصية المولدة أو المترجمة.
`media`	`list[ProjectOperationPlanMediaResponse]`	`True`	—	سجل الجرد لملف العنصر كما في `replace_project_media`؛ يُحذف لعنصر الترجمة.

`ProjectOperationPlanEstimateRequest`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`media_ids`	`list[Annotated[str, Field(max_length=64)]]`	`True`	`Field(min_length=1, max_length=OPERATION_MEDIA_MAX_COUNT)`	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.
`target_language`	`str`	`True`	`Field(min_length=1, max_length=32)`	رمز اللغة الهدف للترجمة النصية المولدة أو المترجمة.
`content_overrides`	`list[ProjectOperationContentOverride]`	`False`	`Field(default_factory=list, max_length=OPERATION_MEDIA_MAX_COUNT * 4)`	تجاوزات مرتبطة بمرجع source_ref ثابت: تفعيل المصدر أو تحديد لغته صراحةً.
`metrics`	`list[ProjectOperationMetricEntry]`	`False`	`Field(default_factory=list, max_length=OPERATION_MEDIA_MAX_COUNT * 4)`	مقاييس المصدر التي تطلبها الخطة الحالية فقط، محسوبة محلياً. مدة الصوت موجودة بالفعل في الجرد المفحوص.

`ProjectOperationPlanEstimateResponse`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`plan`	`ProjectOperationPlanPayload`	`True`	—	خطة غير محفوظة تتضمن مراجع المصادر والخطوات المخططة؛ تُنشأ معرّفات العملية الدائمة عند تأكيد التنفيذ.
`estimate`	`dict[str, Any]`	`True`	—	كائن الخطة أو التقدير أو الاعتماد أو خريطة المصادر المحمية. تبقى بيانات dict[str, Any] مفتوحة؛ يتحقق المثال من الحقول المستخدمة.

`ProjectOperationPlanRequest`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`media_ids`	`list[Annotated[str, Field(max_length=64)]]`	`True`	`Field(min_length=1, max_length=OPERATION_MEDIA_MAX_COUNT)`	سجلات جرد متوافقة مع الخادم أو معرّفات وسائط المشروع المختارة؛ احصل على المعرّفات من الاستجابات الحالية.
`target_language`	`str`	`True`	`Field(min_length=1, max_length=32)`	رمز اللغة الهدف للترجمة النصية المولدة أو المترجمة.
`content_overrides`	`list[ProjectOperationContentOverride]`	`False`	`Field(default_factory=list, max_length=OPERATION_MEDIA_MAX_COUNT * 4)`	تجاوزات مرتبطة بمرجع source_ref ثابت: تفعيل المصدر أو تحديد لغته صراحةً.

`ProjectOperationPlanResponse`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`plan`	`ProjectOperationPlanPayload`	`True`	—	خطة غير محفوظة تتضمن مراجع المصادر والخطوات المخططة؛ تُنشأ معرّفات العملية الدائمة عند تأكيد التنفيذ.

`ProjectOperationResultListResponse`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`results`	`list[ProjectOperationResultResponse]`	`False`	`Field(default_factory=list)`	سجلات مراحل ناجحة وثابتة، بما فيها المراحل المحفوظة بعد فشل مرحلة أخرى.
`total`	`int`	`False`	`0`	مرحلة التقدم المحلي وعدد العناصر أو البايتات المكتملة المقاس؛ الاستدعاءات متزامنة.

`ProjectOperationResultResponse`

كل صف مرحلة ناجحة ثابتة، بما فيها النسخ أو OCR الوسيط والترجمة النهائية. قد تحمل عملية فاشلة جزئياً هذه الصفوف. صدّر artifact_id المختارة؛ يحتاج التحرير نسخة أصل مستقلة قابلة للتحرير.

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`artifact_id`	`str`	`True`	—	معرّف ناتج مرحلة ناجحة وثابتة، كما تعيده قائمة النتائج.
`stage`	`Literal['transcription', 'ocr', 'translation']`	`True`	—	المرحلة المنتجة: نسخ الكلام أو OCR أو الترجمة.
`result_asset_id`	`str`	`True`	—	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`snapshot_id`	`str`	`True`	—	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`generating_artifact_id`	`str`	`True`	—	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`source_asset_id`	`str`	`True`	—	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`source_asset_number`	`int \| None`	`False`	`None`	رقم المصدر داخل عنصر الوسائط الخاص به؛ تضيفه عمليات التصدير إلى الأسماء التي قد تتعارض لولا ذلك (`clip.en.3.srt`).
`source_language`	`str`	`True`	—	لغة المصدر الموحّدة الملتقطة مع الاختيار المحمي.
`target_language`	`str \| None`	`False`	`None`	رمز اللغة الهدف للترجمة النصية المولدة أو المترجمة.
`input_snapshot_id`	`str \| None`	`False`	`None`	سلسلة الأصل المنتج وأصل النتيجة واللقطة الثابتة؛ احتفظ بهذه الهويات عند التصدير.
`content_id`	`str`	`True`	—	معرّف عنصر مصدر داخل العملية، وليس معرّف وسائط مشروع أو ناتج مرحلة.
`operation_media_id`	`str`	`True`	—	العلاقة بين وسائط العملية والمشروع مع مسار الوسائط النسبي المسجل.
`project_media_id`	`str \| None`	`False`	`None`	العلاقة بين وسائط العملية والمشروع مع مسار الوسائط النسبي المسجل.
`media_path`	`str`	`True`	—	العلاقة بين وسائط العملية والمشروع مع مسار الوسائط النسبي المسجل.
`media_name_number`	`int \| None`	`False`	`None`	رقم يميّز العناصر التي تحمل الاسم نفسه في مشروع ملفات (يُعرض كـ `clip.mp4 · 2`)؛ `None` للإدخال الأقدم أو للاسم الفريد.
`export_stem`	`str`	`True`	—	اسم ملف التصدير دون الصيغة (`S01/clip.en`)، قبل ترقيم التعارضات داخل وجهة واحدة.
`language`	`str \| None`	`False`	`None`	لغة الترجمة أو تصنيفها العادي أو الإجباري أو SDH أو التعليق؛ تبقى رموز اللغة التقنية دون تغيير.
`stream_index`	`int \| None`	`False`	`None`	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.
`stream_type`	`str \| None`	`False`	`None`	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`stream_class`	`str \| None`	`False`	`None`	التصنيف العادي أو أي مجموعة من التعليق والإجباري وSDH.
`codec_name`	`str \| None`	`False`	`None`	ترميز المسار الفعلي أو تصنيف الترجمة، بشكل مستقل عن التعرف عند الاستيراد.
`result_created_at`	`str`	`True`	—	وقت إنشاء النتيجة المحفوظة أو عدد مقاطع الترجمة.
`cue_count`	`int`	`False`	`0`	وقت إنشاء النتيجة المحفوظة أو عدد مقاطع الترجمة.

`ProjectOperationSourceRef`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`media_id`	`str`	`True`	`Field(min_length=1, max_length=64)`	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`True`	`Field(min_length=1, max_length=64)`	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.

`SourceObservation`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`files`	`tuple[FileObservation, ...]`	`True`	`Field(min_length=1, max_length=2)`	لقطة مجلد كاملة أو قائمة ملفات أو أدلة ملاحظة تتطلبها نقطة النهاية؛ أنشئها من الملفات المحلية.
`stream_index`	`StrictInt \| None`	`False`	`None`	رقم مسار FFprobe أو أرقام المسارات المحددة للاستبدال، وليس ترتيبها في قائمة مفلترة.
`stream_descriptor`	`dict[Annotated[str, Field(max_length=128)], JsonValue]`	`False`	`Field(default_factory=dict, max_length=128)`	دور الملف الفعلي أو بصمته المرصودة أو وصف المسار المستخدم للفحوص المحمية.

`SourceRef`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`media_id`	`str`	`True`	—	معرّف الوسائط في هذا المسار: معرّف وسائط المشروع لمسارات المشاريع، ومعرّف وسائط العملية للرفع والتحضير.
`asset_id`	`str`	`True`	—	معرّف أصل الترجمة النصية أو الصوت التابع لوسائطه.

`UploadTarget`

سجل هدف مطبّع: expires_at كائن datetime هنا ووقت ISO في HTTP JSON. تحمل الاستجابة أيضاً upload_id وهوية العملية والوسائط والمحتوى وsidecar يقبل الفراغ بالشكل نفسه. headers خريطة نصوص مفتوحة وليست وجهة رمز API. احتفظ بالطريقة والترويسات وأعد تجديد الأهداف المنتهية وأكمل المحاولة والرفع والتجزئة المطابقة فقط.

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`upload_url`	`str`	`True`	—	عنوان من API؛ تُحل العناوين النسبية مقابل البوابة. لا يُرسل رمز SubFT إلى عناوين الرفع.
`method`	`str`	`True`	—	طريقة HTTP؛ احتفظ بالطريقة الصادرة من الخادم عند الرفع المباشر.
`headers`	`Mapping[str, str]`	`True`	—	ترويسات HTTP. مرّر ترويسات هدف الرفع دون تغيير؛ ترويسات الطلب العادي تتجاوز ترويسات المنشئ.
`expires_at`	`datetime`	`True`	—	انتهاء الهدف الموقّع؛ جدّده قبل محاولة رفع منتهية.

`WorkflowPhaseCounts`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`total_phases`	`int`	`False`	`Field(default=0, ge=0)`	عدد مراحل سير العمل بهذه النتيجة. تشمل المراحل المحسومة المكتملة والمتجاوزة والفاشلة.
`resolved_phases`	`int`	`False`	`Field(default=0, ge=0)`	عدد مراحل سير العمل بهذه النتيجة. تشمل المراحل المحسومة المكتملة والمتجاوزة والفاشلة.
`completed_phases`	`int`	`False`	`Field(default=0, ge=0)`	عدد مراحل سير العمل بهذه النتيجة. تشمل المراحل المحسومة المكتملة والمتجاوزة والفاشلة.
`skipped_phases`	`int`	`False`	`Field(default=0, ge=0)`	عدد مراحل سير العمل بهذه النتيجة. تشمل المراحل المحسومة المكتملة والمتجاوزة والفاشلة.
`failed_phases`	`int`	`False`	`Field(default=0, ge=0)`	عدد مراحل سير العمل بهذه النتيجة. تشمل المراحل المحسومة المكتملة والمتجاوزة والفاشلة.

`WorkflowStageFlagsResponse`

الحقل	النوع	مطلوب	التصريح / الافتراض	المعنى
`audio_transcription`	`bool`	`False`	`False`	علامات أو أعداد لكل مرحلة. يصف requested العمل المخطط وneeded العمل المتبقي بعد تخطي المراحل التي لم تبدأ عند التسوية وفق نوع الحقل المتداخل.
`ocr_transcription`	`bool`	`False`	`False`	علامات أو أعداد لكل مرحلة. يصف requested العمل المخطط وneeded العمل المتبقي بعد تخطي المراحل التي لم تبدأ عند التسوية وفق نوع الحقل المتداخل.
`translation`	`bool`	`False`	`False`	علامات أو أعداد لكل مرحلة. يصف requested العمل المخطط وneeded العمل المتبقي بعد تخطي المراحل التي لم تبدأ عند التسوية وفق نوع الحقل المتداخل.