@acedatacloud/sdk هو SDK رسمي من Ace Data Cloud لـ TypeScript / JavaScript، يقوم بتغليف جميع الخدمات الموجودة على api.acedata.cloud في طرق من نوع client.openai.chat.completions.create(...)، client.images.generate(...)، client.search.google(...) وغيرها، ويأتي مع تدفق SSE، وإعادة المحاولة مع التراجع، واستثناءات من نوع محدد.
يمكن استخدامه في Node.js وDeno وBun والمتصفحات الحديثة (مع bundler).
عنوان المصدر والحزمة:
- مستودع SDK: https://github.com/AceDataCloud/SDK
- npm SDK: https://www.npmjs.com/package/@acedatacloud/sdk
التثبيت
- إصدار الحزمة هو
2026.504.2(CalVer، الإصدار الثاني من الأسبوع ISO 504 في عام 2026). AceDataCloudهو الفئة الرئيسية المستخدمة لبناء العميل، ويمكن الوصول إليها من التصدير الافتراضي.
إعداد API Token
راجع نظرة عامة على SDK - طلب API Token للحصول على الرمز، ثم في shell قم بـexport:
apiToken، سيقوم SDK بقراءة متغير البيئة ACEDATACLOUD_API_TOKEN تلقائيًا. إذا كان لديك بالفعل ACEDATACLOUD_API_KEY في بيئتك (وفقًا لاتفاقية مستودع المشروع)، يمكنك تمريره بشكل صريح: new AceDataCloud({ apiToken: process.env.ACEDATACLOUD_API_KEY }).
مثال 1: chat.completions (غير متدفق)
id chatcmpl-DldCcLvkTFaioST8e6SjOl0wJScQAهو معرف استجابة متوافق مع OpenAI، يمكن العثور على السجل المقابل في استخدامات وحدة التحكم.content ADC_TS_SDK_OKهو المعرف الثابت الذي تم إرجاعه فعليًا من النموذج، مما يثبت أن الاستجابة لم يتم تعديلها بواسطة SDK.- تستهلك عملية chat completion واحدة حوالي 22 توكن، وفقًا لسعر gpt-4o-mini.
- يعلن SDK عن الاستجابة كـ
Record<string, unknown>، وفي وقت التشغيل تكون كائن JSON، يمكن الوصول إليها باستخدام.id/.choices[0].message.content، وهذا يعمل في.mjs، Node REPL، وBun؛ قد تحتاج المشاريع الصارمة في TypeScript إلى(res as any).idأو إيقافnoImplicitAnyفي tsconfig.
مثال 2: chat.completions (SSE متدفق)
عند فتحstream: true، تعيد create مكررًا غير متزامن، كل إطار هو ChatCompletionChunk.
- تأخير الإطار الأول 2481 مللي ثانية هو الوقت الذي استغرقه النموذج لتوليد أول توكن؛ وصلت الإطارات الـ 12 التالية جميعها في 135 مللي ثانية.
- الإطارات الـ 13 مجتمعة هي
"1 2 3 4 5"، كل توكن في إطار منفصل + الإطار الأخير يحملfinish_reason. - التدفق المتزامن لا يوفر توكن أكثر من غير المتزامن، لكن تأخير الحرف الأول ينخفض بشكل ملحوظ، مما يجعله مناسبًا لإنشاء واجهات مستخدم حية.
مثال 3: images.generate (NanoBanana)
client.images.generate({ provider: 'nano-banana', ... }) تعيد مباشرة بشكل متزامن، لا تحتاج إلى تمرير معلمة wait - واجهة برمجة تطبيقات NanoBanana نفسها تولد بشكل متزامن.
image_urlهو عنوان ثابت على CDN، يمكن استخدامه مباشرة في<img src />أو تنزيله.- معظم الوقت في 16.6 ثانية هو وقت استدلال النموذج، ويمكن تجاهل تكلفة SDK المحلية.
trace_idهو معرف الطلب المخصص من المنصة، إذا حدثت مشكلة، يمكنك لصق هذا المعرف لخدمة العملاء لتحديد الموقع بسرعة.- بالنسبة للخدمات غير المتزامنة (مثل Midjourney وSora وVeo وغيرها) تحتاج إلى استعلام TaskHandle، راجع استعلام SDK والردود المتدفقة.
المثال 4: معالجة الأخطاء المُنمَّطة
يرمي SDK الأخطاء كفئات فرعية محددة وفقًا لحالة HTTP (مثلAuthenticationError / BadRequestError / RateLimitError / InternalServerError / APIConnectionError)، ويمكن استخدام instanceof للتفرع بدقة.
- يتم تعيين 401 تلقائيًا إلى
AuthenticationError، ويمكن لرمز العمل استخدامinstanceofللتفرع بدقة. - يشير
code: invalid_tokenإلى أن مفتاح API غير صالح؛ يُرجى التحقق من بيانات الاعتماد. - وبالمثل: 429 →
RateLimitError، و400 →BadRequestError، و5xx →InternalServerError.
المثال 5: توجيه نماذج متعددة
يمكن للعميل نفسه التبديل بحرية بين خدمات متعددة، ما دام اسم النموذج متطابقًا.- قاعدة تعليمات برمجية واحدة ورمز token واحد، لتغطية أربعة أنواع من خدمات النماذج: OpenAI / Google / DeepSeek / xAI.
- لم يُرجع
gemini-2.5-flashهذه المرةADC_OK، وهذا اختلاف في أسلوب إخراج النموذج نفسه — لم تقم SDK بحذف أي شيء بصمت، بل مرّرت كلام النموذج الأصلي بأمانة إلى التطبيق. - تُحتسب الأسعار وفق سعر token الخاص بكل نموذج.
مثال 6: بحث Google
- تم الحصول على 10 نتائج عضوية من طلب واحد، اسم الحقل هو
organic(ليسorganic_results). - البحث يتم عبر خدمة Serp ويتم احتسابه حسب الطلب.
- يمكن لنموذج العميل نفسه إجراء الدردشة والبحث، توكن واحد يكفي.
خيارات التكوين
استخدام المتصفح
@acedatacloud/sdk هو حزمة ESM + ISO (متجانسة)، يمكن استخدامها مباشرة في المتصفحات الحديثة التي تحتوي على bundler. ملاحظة: لا تقم بتشفير توكن API في كود الواجهة الأمامية. يوصى في الواجهة الأمامية:
- استخدام X402
paymentHandler- محفظة المستخدم تدفع USDC حسب الطلب، دون الحاجة إلى توكن. - أو استخدام SDK على خادمك الخاص، حيث يقوم المتصفح فقط باستدعاء الخلفية الخاصة بك.
متقدم: استعلام المهام والتجاوب المتدفق
- خدمات المهام (Midjourney، Sora، Veo، Suno): استخدم
TaskHandleللاستعلام، التفاصيل المتعلقة بالوحدات، المهلة وإعادة المحاولة انظر SDK استعلام المهام والتجاوب المتدفق. - الدردشة المتدفقة: تم عرضها في المثال 2 في هذه الصفحة؛ تدفق الصوت / الفيديو مدعوم أيضًا.
متقدم: خطاف دفع X402
إذا كنت لا ترغب في طلب توكن API، وترغب في الدفع حسب الطلب على السلسلة، يمكنك استخدامpaymentHandler:
createX402PaymentHandlerفي جانب TypeScript يقبل{ network, evmProvider, evmAddress, preferScheme? }(سلسلة EVM) أو{ network: 'solana', solanaWallet }(Solana). في خادم Node عندما لا يوجدwindow.ethereum، يرجى استخدامviemلإنشاءcreateWalletClient(استنادًا إلى المفتاح الخاص) لتغليف مزود متوافق مع EIP-1193 ثم تمريره؛ انظر التفاصيل والطريقة الحقيقية والنتائج على السلسلة في SDK + خطاف دفع X402.

