مرجع API الخاص بـ tAI

نقطة النهاية

كل شيء في هذا الـ API يمر عبر عنوان URL واحد:

# Base URL
https://api.artfical.com/v1

توجد نقطة نهاية إكمال واحدة، POST /v1/chat/completions، ونقطة نهاية سرد للقراءة فقط، GET /v1/models. هذا هو السطح الكامل للـ API. لا توجد نقطة نهاية منفصلة لكل نموذج، ولا نقطة نهاية منفصلة للبث مقابل الاستجابة غير المتدفقة (نفس عنوان URL يتعامل مع الحالتين، ويتم التبديل بينهما عبر حقل في جسم الطلب)، ولا نقطة نهاية منفصلة لأدوار استدعاء الأدوات. إذا سبق أن بنيت شيئًا فوق واجهة Chat Completions الخاصة بـ OpenAI، أو نقاط نهاية الاستدلال في GitHub، أو أيًا من مزودي الخدمة الكثيرين الذين يقدّمون شكلاً متوافقًا مع OpenAI، فسيبدو هذا مألوفًا لك بالفعل. هذا التشابه مقصود: توجيه عميل متوافق مع OpenAI لديك أصلاً (حزمة openai الرسمية بلغة Python أو Node، أو LangChain، أو LlamaIndex، أو وكيل برمجي مثل OpenCode، أو غلاف خفيف من صنعك) نحو https://api.artfical.com/v1 مع مفتاح API الخاص بـ tAI يجب أن يعمل بأدنى قدر من التعديل أو بلا تعديل على الإطلاق.

أقصر طريق لأول طلب

هناك ثلاثة أشياء مطلوبة: مساحة عمل على console.artfical.com، ومفتاح API تم إنشاؤه من صفحة مفاتيح API في مساحة العمل تلك، وأي عميل HTTP. إليك أقصر نسخة، باستخدام curl:

# استبدل tai-sk-... بمفتاحك الخاص
curl https://api.artfical.com/v1/chat/completions \
  -H "Authorization: Bearer tai-sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tai-4.1",
    "messages": [{"role": "user", "content": "Merhaba, kendini tanıt."}]
  }'

هذا الطلب الواحد هو تكامل كامل وعامل. كل ما سواه في هذا القسم، البث، واستدعاء الأدوات، وإدخال الصور، وضوابط أخذ العينات، هو طبقة اختيارية فوق هذا الشكل نفسه، وليس واجهة API مختلفة يجب تعلمها من جديد. صفحة إكمالات المحادثة تشرح الطلب والاستجابة بالتفصيل الكامل؛ وصفحة المصادقة تغطي كيفية إصدار المفتاح نفسه ونطاق صلاحياته وتدويره.

كيفية تنظيم هذا القسم

الصفحات هنا مُجمّعة بحيث تطابق الترتيب الذي يحتاجه معظم الناس فعليًا، وليس الترتيب الذي يصادف أن يُنظَّم به التطبيق الداخلي الكامن وراءها. المجموعة الأولى، البدء، هي الجزء الذي يحتاجه الجميع بصرف النظر عمّا يبنونه: كيفية المصادقة، وشكل الطلب والاستجابة، وكيف يختلف البث عن استجابة حاجبة واحدة، وكيفية اكتشاف النماذج الموجودة وما تكلفه كل واحدة منها وما تدعمه. المجموعة الثانية، خيارات الطلب، تغطي كل ما هو اختياري فوق طلب أساسي: مقابض أخذ العينات التي تشكّل طريقة توليد الاستجابة، وكيفية منح النموذج أدوات يمكنه طلب استدعائها، وكيفية إرسال صورة إلى جانب النص. المجموعة الثالثة، المرجع، مقصود منها أن تُستخدم للبحث السريع لا أن تُقرأ من البداية للنهاية: الشكل الدقيق لاستجابة الخطأ وما يعنيه كل نوع، وكيفية عمل تحديد المعدل وما الترويسات (headers) التي تعكسه، وجدول التسعير لكل نموذج، وصفحة مخصصة لكل من يُهاجر تكاملاً قائمًا على SDK الخاص بـ OpenAI، تغطي ما هو مدعوم كما هو وما ليس كذلك.

لمن هذا القسم

كُتب هذا القسم لشخص يكتب كودًا يتعامل مع الـ API مباشرة، سواء كان ذلك خدمة خلفية، أو سكربتًا، أو إطار عمل وكيلي مثل OpenCode يعامل tAI كأحد عدة مزودين متوافقين مع OpenAI وقابلين للتبديل. يفترض هذا القسم إلمامًا بإجراء طلبات HTTP وقراءة JSON، لكن دون أي معرفة مسبقة بـ tAI تحديدًا. إذا كنت تبحث بدلاً من ذلك عن كيفية استخدام tAI عبر منتج الدردشة نفسه، فذلك مشمول في وثائق tAI الرئيسية، لا في هذا القسم. وإذا كنت تبحث عن كيفية تقييم tAI من حيث السلامة وما الضمانات التي بُني عليها المنتج، فذلك قسم الأمان. هذا القسم مخصص تحديدًا لواجهة HTTP الموجهة للمطورين: ما ترسله، وما تحصل عليه، وماذا يعني كل حقل وترويسة.

ملاحظة حول الاستقرار

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