الانتقال إلى المحتوى الرئيسي
ثبّت حزمة Phaseo الخاصة بلغتك، وأنشئ عميلًا باستخدام مفتاح API الخاص بك، واستدعِ دالة واحدة لكل نقطة نهاية في Gateway. تقرأ كل حزمة SDK المتغير PHASEO_API_KEY عندما لا تمرّر مفتاحًا. تحتوي صفحة التثبيت على أمر التثبيت والمتطلبات لكل لغة. لم تُطرح بعد حزمة SDK للغة C++.

ما ترسله وما تحصل عليه

تستخدم أجسام الطلبات أسماء حقول JSON الخاصة بالواجهة البرمجية في كل حزمة SDK. تحتوي صفحة الاستخدام على مثال واحد لكل نقطة نهاية. يفشل إنشاء العميل عند غياب المفتاح. تطلق Python الخطأ ValueError، وتعيد NewFromEnv() في Go خطأً، وتطلق C# وPHP الخطأ Missing API key. Pass apiKey or set PHASEO_API_KEY.، وتطلق Ruby الخطأ ArgumentError: Missing API key. Pass api_key or set PHASEO_API_KEY.، وتعيد Phaseo::from_env() في Rust قيمة PhaseoError.

العثور على الدالة لكل نقطة نهاية

تعني الشَّرطة أن حزمة SDK لا تتضمن مغلّفًا لتلك العملية. استخدم الدالة الموجودة في الصف الأخير، أو استدعِ HTTP API مباشرة. تعني “JSON فقط” أن الدالة لا تستطيع إرسال رفع ملف متعدد الأجزاء: مرّر عنوان URL أو عنوان data URL بترميز base64 بدلًا من ذلك، أو أرسل الرفع باستخدام عميل HTTP الخاص بلغتك كما تعرض صفحة نقطة النهاية. تتضمن معظم حزم SDK أيضًا اسمًا بديلًا create… لكل دالة generate… (مثل CreateChatCompletion في Go وC#، وcreate_response في Ruby). تتضمن C# وPHP وRuby وJava دالة للرفع، لكنها ترسل بيانات JSON ولا تستطيع رفع ملف؛ وتعرض صفحتا الملفات وSTT الطلب متعدد الأجزاء في كل لغة. تتضمن المفاتيح ومساحات العمل أيضًا دوال get وupdate وdelete ودالة للبحث عن المفتاح الحالي (getCurrentApiKey وget_current_api_key وGetCurrentApiKey) في كل حزمة SDK باستثناء Rust. تغطي TypeScript وPython أيضًا الموسيقى، وOCR، والتحليل (parse)، والقرارات، والاستخراج.

ما الذي تتضمنه كل حزمة

تسبق الحزم المنشورة بعض الميزات الموجودة في مصدر حزم SDK:

إعداد العميل

انتظار الموسيقى أو الفيديو أو الدفعات

دوال الانتظار المساعدة موجودة في TypeScript وPython. تعيد حزم SDK الأخرى المهمة من استدعاء الإنشاء؛ استطلعها باستخدام دالة الجلب أو افتح عنوان WebSocket للمهمة.
استخدم videos.generateAndWait / videos.generate_and_wait للفيديو وbatches.createAndWait / batches.create_and_wait للدفعات. ترسل كل دالة مساعدة الطلب مرة واحدة. إذا كانت الاستجابة الأولى مكتملة بالفعل، تعيدها دون استطلاع؛ وإلا فإنها تستطلع المهمة نفسها حتى تنتهي وتعيد الاستجابة كاملة. تطلق المهام الفاشلة أو الملغاة أو المنتهية الصلاحية الخطأ JobFailedError، الذي يحتوي response الخاص به على التفاصيل. قد تحتوي الدفعة المكتملة مع ذلك على طلبات فردية فاشلة. تستأنف wait(id, options) على كل مورد مهمة موجودة وتعيد أي استجابة نهائية، بما في ذلك الإخفاقات. في Python، تتضمن الموسيقى أيضًا create(request) وretrieve(id). يحتفظ JobTimeoutError وJobCancelledError بمعرّف المهمة وآخر استجابة (jobId/lastResponse في TypeScript، وjob_id/last_response في Python)، لذا يمكنك الاستئناف باستخدام .wait(error.jobId) أو .wait(error.job_id). لا يؤدي إيقاف الانتظار إلى إلغاء المهمة البعيدة. في TypeScript، يُلغي الاستطلاع الجاري؛ أما عميل Python المتزامن فيتحقق من الإلغاء والمهلة النهائية بين الطلبات والاستدعاءات الراجعة، لذا لا يمكنه مقاطعة استدعاء HTTP قيد التنفيذ. تُطلق إخفاقات HTTP كما هي، ولا يُعاد إرسال الطلبات أبدًا. تستطلع هذه الدوال المساعدة من عمليتك؛ ولا تضيف تنفيذًا في الخلفية إلى البوابة.

الاحتفاظ بمقبض عبر العمليات

تعيد music.start وvideos.start وbatches.start مقبضًا يتضمن result() وevents() وcancel()، إضافة إلى toJSON() (في TypeScript) أو to_dict() (في Python). خزّن النوع والمعرّف اللذين يعيدهما وأعد بناء المقبض لاحقًا باستخدام resume(id). تطلق result() خطأً عند الإخفاقات النهائية. لا تدعم cancel() إلا مهام الفيديو والدفعات. على AsyncPhaseo، استخدم await مع الدوال وكرّر على الأحداث باستخدام async for.

عناصر التحكم في الطلب والأخطاء

القيمة الافتراضية لإعادة المحاولة 0 في TypeScript وPython وJava، ولا تنطبق إلا على طلبات GET وHEAD. لا يُعاد أبدًا إرسال الطلبات المدفوعة ولا عمليات الكتابة ولا طلبات البث.
تعيد withOptions(...) عميلًا جديدًا تُطبَّق فيه عناصر التحكم تلك على كل استدعاء للموارد والبث والوسائط؛ ويبقى العميل الأصلي دون تغيير. تحترم إعادة المحاولة Retry-After. تشمل timeoutMs قراءة جسم الاستجابة.تعيد responseMetadata(result) معرّف طلب البوابة وعنوان URL للتتبّع في لوحة التحكم. أخطاء HTTP من النوع PhaseoHttpError، وتتضمن status الخاص بـ HTTP، وcode الخاص بخطأ الواجهة البرمجية، وrequestId، وtraceUrl، ومهلة إعادة المحاولة، والجسم، وheaders.
تعرض صفحة الاستخدام معالج أخطاء كاملًا في كل لغة.

استدعاء نقطة نهاية دون مغلّف

تتضمن كل حزمة SDK أيضًا العميل المولَّد من مواصفة Phaseo OpenAPI: العمليات المولَّدة أدنى مستوى من دوال المغلّف؛ فضّل المغلّف حيثما وُجد.

تحليل المخرجات وتجميع البث

هذه الدوال المساعدة موجودة في TypeScript وPython. تتحقق responses.parse(request, schema) من استجابة JSON مكتملة. في TypeScript، يكون schema محلّلًا متوافقًا مع Zod؛ وفي Python، نموذج Pydantic. عيّن تنسيق المخرجات المنظَّمة في الطلب أيضًا؛ فالمحلّل يتحقق فقط. تجمع collectStream(client.streamResponses(request)) (في TypeScript)، أو collect_stream وcollect_async_stream (في Python)، النص المبثوث والاستخدام.

التحقق من نموذج قبل استدعائه

تتحقق checkModelCapabilities / check_model_capabilities (في TypeScript وPython) من القدرات المعلنة والقيود العددية (inputTypes وoutputTypes وendpoints وparameters وparameterValues، أو الأسماء بأسلوب snake_case في Python) على عرض مزوّد نشط واحد. لا تغيّر النموذج أبدًا ولا تحذف معاملات، ولا يمكنها ضمان أن يقبل المزوّد الحي الطلب. تختلف معالجة البيانات الوصفية المفقودة: تُبلغ TypeScript عنها بوصفها غير معروفة، وتُفشل Python الفحص. لمنتقيات النماذج ومحررات المعاملات، استخدم البيانات الوصفية الحية لنقاط النهاية:
يعود كل معامل بالقيمة supported أو partial أو unsupported أو unknown، مع مسارات المزوّدين المطابقة ومشكلات القيود التي يمكنك إبرازها مباشرة في الواجهة. هذه الفحوص استدعاءات صريحة؛ ولا تضيف بحثًا إلى طلبات التوليد. تسرد صفحة النماذج الدالة في كل حزمة SDK.

الاختبار دون شبكة

استورد createMockTransport وjobFixtures من @phaseo/sdk/testing ومرّر fetchImpl الخاص بالمحاكاة إلى العميل. البيانات الثابتة (fixtures) صارمة ومرتّبة: يفشل أي استدعاء غير متوقع محليًا ولا يصل أبدًا إلى الشبكة. استدعِ mock.assertDone() للتحقق من حدوث كل طلب متوقع.

تصدير الشيفرة من غرفة

بعد أن ترسل طلبًا في غرفة Phaseo، يصدّر الحصول على الشفرة نموذجه وإعداداته بلغة TypeScript أو Python، ويفتح عرض الطلب تتبّعه في لوحة التحكم عند توفر معرّف طلب. شغّل الشيفرة المصدَّرة على خادمك مع تعيين PHASEO_API_KEY.
آخر تعديل في ٥ نوفمبر ٢٠٢٦