وثائق API

البدء

يمكن سرد النماذج المتاحة الآن في أي وقت:

curl https://babelmesh.ai/v1/models \
  -H "Authorization: Bearer $BABEL_KEY"

إذا لم تعرف أي نموذج تختار، فاستخدم auto. ينظر Babel Mesh في الطلب: الحديث العابر والأسئلة البسيطة تذهب إلى نموذج سريع؛ والشيفرة إلى نموذج برمجي؛ والاستدلال والمواد الطويلة جدًا واستدعاءات الأدوات والمخرجات المنظّمة إلى أقوى نموذج؛ وإذا لم يكن لنموذج ما عقدة أو كان طابوره طويلًا يُستخدم نموذج آخر. لا يقرأ القرار إلا الطلب نفسه (طوله، وهل فيه شيفرة أو أدوات أو مخطط مخرجات منظّمة) ولا يُخزَّن شيء. ترويسة الاستجابة X-Gateway-Model تبيّن أي نموذج أجاب وX-Gateway-Auto تبيّن السبب. لا يختار auto إلا النماذج التي يحق لحسابك استخدامها.

يمكنك أيضًا تسمية نموذج: chat-default (سريع)، chat-strong (قوي)، embedding-default (تضمينات)، video-default (فيديو). وللصور استخدم اسم النموذج z-image-turbo (ويعمل auto أيضًا لطلبات الصور). الاسم المستعار يشير إلى الأنسب حاليًا؛ واسم النموذج نفسه يعمل أيضًا.

الدردشة

نقطة النهاية هي POST /v1/chat/completions؛ وstream: true يبثّ الإجابة.

curl https://babelmesh.ai/v1/chat/completions \
  -H "Authorization: Bearer $BABEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Introduce yourself in one sentence"}]
  }'

مع حزمة OpenAI لـ Python:

from openai import OpenAI

client = OpenAI(base_url="https://babelmesh.ai/v1", api_key="sk-fab-...")

stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Write a Python function that checks for palindromes"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

التضمينات

نقطة النهاية هي POST /v1/embeddings؛ وinput نص أو قائمة نصوص.

curl https://babelmesh.ai/v1/embeddings \
  -H "Authorization: Bearer $BABEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "embedding-default", "input": ["a lighthouse at dawn", "a paper boat on a pond"]}'

الصور

نقطة النهاية هي POST /v1/images/generations؛ وتعود الصورة بصيغة base64 (data[0].b64_json).

curl https://babelmesh.ai/v1/images/generations \
  -H "Authorization: Bearer $BABEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "z-image-turbo", "prompt": "a lighthouse at dawn, watercolor", "n": 1}'

الفيديو

يستغرق الفيديو دقائق، لذا هو مهمة غير متزامنة: أرسلها، واستعلم عن حالتها، ثم اجلب الملف.

# 1. Submit; the answer holds a job id
curl https://babelmesh.ai/v1/videos \
  -H "Authorization: Bearer $BABEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "video-default", "prompt": "a paper boat on a pond", "seconds": "3"}'

# 2. Poll: queued, in_progress, completed or failed
curl https://babelmesh.ai/v1/videos/VIDEO_ID -H "Authorization: Bearer $BABEL_KEY"

# 3. When completed, fetch the video (mp4)
curl https://babelmesh.ai/v1/videos/VIDEO_ID/content -H "Authorization: Bearer $BABEL_KEY" -o out.mp4

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

استخدامه من تطبيقات أخرى

لأن الواجهة متوافقة مع OpenAI، فهي تعمل مع واجهات الدردشة مثل Open WebUI وCherry Studio وChatbox، ومع إضافات الذكاء الاصطناعي في المحررات. أضِفها كمزوّد "متوافق مع OpenAI" بإعدادين:

• لا تعرف هذه التطبيقات واجهة مهام الفيديو (إرسال، استعلام، جلب)؛ فللفيديو استدعِ الواجهة مباشرةً كما سبق.
• يبقى سجل المحادثات في تطبيقك؛ ولا يخزّنه Babel Mesh. يُعالج المحتوى وفق فئة بيانات الحساب، وهي "عامة" افتراضيًا وقد تعمل على حواسيب المساهمين: لا تُدخل مواد خاصة أو سرية.
• إذا نشرت تطبيقًا كهذا لعدة أشخاص، فإنهم جميعًا يتشاركون أرصدة المفتاح الواحد وحدوده.

الواجهة المحلية للعميل

يستطيع عميل Babel Mesh أيضًا أن يجيب على حاسوبك أنت، فتستخدم البرامج هناك الشبكة كما تستخدم نموذجًا محليًا. وهو متوقف إلى أن تشغّل "API المحلية" في صفحة حساب العميل. ولا يستمع إلا على هذا الحاسوب (المنفذ الافتراضي 18650؛ ويعرض العميل العنوان الدقيق)، وتستخدم البرامج رمزًا يعرضه العميل، لا مفتاح حسابك.

• الأدوات التي تتوقع Ollama على منفذه المعتاد 11434 تُخدم هناك أيضًا، لكن فقط عندما لا يكون Ollama نفسه مثبّتًا أو قيد التشغيل على ذلك الحاسوب، فلا يتنازع الاثنان على المنفذ أبدًا.
• يعمل مع Claude Code وOpen WebUI وContinue وCursor وCherry Studio وLobeChat وحزم SDK الخاصة بـ OpenAI وOllama.
• تتابع الطلبات إلى الشبكة باسم حسابك، فتُستهلك الأرصدة كالمعتاد وتسري فئة البيانات نفسها.

من مكان آخر، بالحساب نفسه

يمكن الوصول إلى العنوان العام https://babelmesh.ai/v1 من أي مكان بمفتاح حسابك، فيستطيع حاسوب آخر أو خادم أو تطبيق هاتف الاتصال به مباشرةً. اليوم يتحدث هذا العنوان واجهة API المتوافقة مع OpenAI. وللأدوات بأسلوب Ollama وAnthropic على حاسوب آخر، ثبّت العميل هناك وسجّل الدخول بالحساب نفسه واستخدم واجهته المحلية كما سبق. لا يفتح العميل أي منفذ وارد، لذا لا يمكن الوصول إلى واجهته المحلية من أجهزة أخرى.

مخطط له، بلا موعد: نقاط نهاية بأسلوب Anthropic وOllama على العنوان العام أيضًا.

الأخطاء والحدود

للأخطاء شكل OpenAI: {"error": {"message": "...", "type": "..."}}. رصيدك وحدودك: GET /v1/account.