دمج Brainiall في تطبيقك بـ Python أو Node.js

intermediario · 10 min · Por Ana Brainiall

API الخاصة بـ Brainiall متوافقة مع OpenAI

إذا كنت تعرف كيف ترسل طلبات إلى API الخاصة بـ OpenAI، فأنت تعرف كيف تتعامل مع Brainiall. هناك فرقان فقط:

1. Base URL: https://api.brainiall.com/v1 (بدلاً من https://api.openai.com/v1)
2. API Key: بصيغة brnl-... (بدلاً من sk-...)

كل شيء آخر متطابق تماماً. الكود الموجود لديك يعمل بمجرد تغيير هذين القيمتين.

diagrama simples mostrando uma lib OpenAI SDK sendo configurada com 2 overrides

الخطوة 1: إنشاء API Key الخاصة بك

1. ادخل إلى https://app.brainiall.com
2. سجّل الدخول بحساب Google (إذا كانت المرة الأولى)
3. القائمة ← API Keys ← "إنشاء مفتاح جديد"
4. أعطِه اسماً وصفياً (مثل "my-app-prod")
5. انسخ المفتاح — يظهر مرة واحدة فقط، احتفظ به جيداً

خطة Pro بـ 29 ريال تتيح مفتاحاً واحداً نشطاً؛ خطة Business تشمل رصيداً + مفاتيح متعددة + تدوير تلقائي.

الخطوة 2: Python مع httpx

`python
import httpx

BASE = "https://api.brainiall.com/v1"
KEY = "brnl-d13..." # مفتاحك

def chat(prompt, model="claude-sonnet-4-6"):
r = httpx.post(
f"{BASE}/chat/completions",
json={
"model": model,
"messages": [{"role": "user", "content": prompt}]
},
headers={"Authorization": f"Bearer {KEY}"},
timeout=60
)
r.raise_for_status()
return r.json()["choices"][0]["message"]["content"]

print(chat("اشرح TLS في جملتين."))
`

الخطوة 3: Python مع SDK الرسمي لـ OpenAI

`python
from openai import OpenAI

client = OpenAI(
base_url="https://api.brainiall.com/v1",
api_key="brnl-xxx"
)

r = client.chat.completions.create(
model="claude-sonnet-4-6",
messages=[{"role": "user", "content": "مرحباً!"}]
)
print(r.choices[0].message.content)
`

يعمل SDK الخاص بـ OpenAI بنسبة 100% — ندعم streaming وfunction calling وtool_use وvision وجميع معايير OpenAI.

الخطوة 4: Node.js

`javascript
import OpenAI from 'openai';

const client = new OpenAI({
baseURL: 'https://api.brainiall.com/v1',
apiKey: 'brnl-xxx'
});

const r = await client.chat.completions.create({
model: 'claude-sonnet-4-6',
messages: [{ role: 'user', content: 'مرحباً!' }]
});
console.log(r.choices[0].message.content);
`

النماذج المتاحة

استخدم endpoint الخاص بـ /v1/models لعرض القائمة في الوقت الفعلي:

`python
r = httpx.get(f"{BASE}/models", headers={"Authorization": f"Bearer {KEY}"})
for m in r.json()["data"]:
print(m["id"])
`

الفئات:
- نصي: claude-sonnet-4-6, gpt-5, gemini-3-pro, llama-4-maverick, deepseek-v3, وغيرها.
- صور: gemini-3-flash-image, gpt-5-image, flux-2-klein, seedream-4.5
- فيديو (endpoint منفصل /v1/videos): bytedance/seedance-2.0-fast
- TTS (endpoint /v1/audio/speech): 54 صوتاً
- STT (endpoint /v1/audio/transcriptions): Whisper Large v3

Streaming (server-sent events)

`python
with httpx.stream("POST", f"{BASE}/chat/completions", ...
json={"model": "...", "messages": [...], "stream": True}
) as r:
for line in r.iter_lines():
if line.startswith("data: "):
# parse chunk JSON
...
`

يُقلّل Streaming من زمن الاستجابة المحسوس بشكل كبير — تظهر الرموز أثناء التوليد بدلاً من انتظار الاستجابة الكاملة.

حدود الاستخدام وأفضل الممارسات

الطبقة المجانية لـ API: غير متاحة — تتطلب API خطة Pro أو Business
Pro بـ 29 ريال: تشمل الدردشة والصور عبر البوابة، والـ API بالدفع حسب الاستخدام
Business بـ 99 ريال: تشمل رصيداً شهرياً بقيمة 50 ريال للـ API
إعادة المحاولة: استخدم exponential backoff للأخطاء 429/5xx
التخزين المؤقت: احفظ الاستجابات الثابتة محلياً
Timeout: 60 ثانية آمنة؛ للمهام الطويلة كالفيديو استخدم 300 ثانية

الأخطاء الشائعة

نسيان Bearer قبل المفتاح ← خطأ 401
تضمين المفتاح مباشرة في الكود ← تسريب محتمل عند رفع الكود على git؛ استخدم متغيرات البيئة
عدم معالجة خطأ 429 ← توقف التطبيق
تجاهل usage في الاستجابة ← مفاجأة في الفاتورة
استخدام نموذج مكلف لمهمة بسيطة ← تكلفة أعلى 10 أضعاف دون داعٍ

جرّبه الآن

أنشئ مفتاحك على https://app.brainiall.com وشغّل أحد الأمثلة أعلاه. خطة Pro بـ 29 ريال هي الحد الأدنى للوصول إلى API؛ وخطة Business بـ 99 ريال تشمل رصيداً كافياً للبدء فوراً.