المرجع الكامل لـ AI API — للبشر وللآلة

1. نظرة عامة

هذه الصفحة هي المرجع الكامل لواجهة نماذج AI — بوابة متوافقة مع OpenAI تتيح استدعاء عشرات النماذج (GPT وDeepSeek والتمثيلات…) باسمك. هي منصة مستقلة عن واتساب API، لها توثيقها وصفحة أسعارها وصفحة أسئلتها الخاصة: وكل ما في هذه الصفحة يخص AI وحدها.

يستدعي تطبيقك POST /api/v1/chat بمفتاح sk_؛ ومفتاح المزود الخارجي لا يغادر المنصة أبداً، وكل استدعاء يُحتسب بالتوكنات على رصيد المستدعي. أما مرجع واتساب (الجلسات والإرسال وإشعارات التسليم) ففي صفحته الخاصة /docs.

بيانا الدخول اللذان ستواجههما

2. البدء السريع

الرابط الأساسي: https://masarroute.com. كل طلب ورد بـ JSON وUTF-8. ثلاث خطوات: اقرأ الكتالوج العام، أنشئ مفتاح sk_، ثم نفّذ أول استدعاء محادثة.

# Public catalog — model ids with final input/output prices per 1M tokens
curl https://masarroute.com/api/v1/ai/models

1. أنشئ مفتاح sk_ من لوحة العميل ← AI ← المفاتيح (POST /api/v1/ai/keys). يُعرض مرة واحدة ويُخزَّن مُجزّأاً.
2. اختر باقة رصيد: الباقة المجانية تتفعّل فوراً (POST /api/v1/ai/subscription/subscribe)، والمدفوعة تعود بـ PAYMENT_REQUIRED حتى يتأكد الدفع.
3. استدعِ النموذج — والبوابتان (الباقة الفعّالة والرصيد المتبقي) تعودان بـ 402 أو 429 عند نفاد أيٍّ منهما.

# OpenAI-compatible chat — your sk_ key, our metering in tokens
curl -X POST "https://masarroute.com/api/v1/chat" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

{
  "success": true,
  "model": "gpt-4o-mini",
  "response": "Hello! How can I help you today?",
  "usage": { "prompt_tokens": 12, "completion_tokens": 30, "total_tokens": 42 },
  "cost": { "sale_price": 0.0001 }
}

من opencode أو أي مكتبة OpenAI

‏POST /api/v1/chat/completions يتكلّم OpenAI خالصاً: جسم الطلب يمرّ كما هو دون تحويل (‏tools وtool_choice وtemperature وmax_tokens…)، وstream:true يُجاب ببث SSE، والأخطاء بصيغة OpenAI ‏(error.message). وGET /api/v1/models يدرج النماذج بصيغة OpenAI — وكلاهما يُفوَّت بالطريقة نفسها تماماً مثل POST /api/v1/chat. والنماذج المجانية (سعر بيع صفري) تعمل بمفتاح sk_ فقط — دون اشتراك أو رصيد؛ والمدفوعة تتطلب باقة فعّالة بحصة أو رصيداً دولارياً.

# SSE streaming — usage arrives in the final chunk before [DONE]
curl -N -X POST "https://masarroute.com/api/v1/chat/completions" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","messages":[{"role":"user","content":"Hello"}],"stream":true}'

{
  "provider": {
    "rawi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Rawi AI",
      "options": { "baseURL": "https://masarroute.com/api/v1" },
      "models": { "gpt-6-sol": {}, "claude-sonnet-5.5": {} }
    }
  }
}

أضف المفتاح من شاشة /connect ← Other ← معرّف المزوّد rawi (يُخزَّن في options.apiKey)، ثم اختر أي معرّف نموذج يعيده GET /api/v1/models.

أمثلة بلغتك

$ch = curl_init("https://masarroute.com/api/v1/chat");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST          => true,
  CURLOPT_HTTPHEADER    => ["X-API-Key: sk_live_...", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS    => json_encode([
    "model"    => "gpt-4o-mini",
    "messages" => [["role" => "user", "content" => "Hello"]],
  ]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $data["response"];

use Illuminate\Support\Facades\Http;

$res = Http::withHeaders(["X-API-Key" => config("services.ai.key")])
    ->post("https://masarroute.com/api/v1/chat", [
        "model"    => "gpt-4o-mini",
        "messages" => [["role" => "user", "content" => "Hello"]],
    ])
    ->throw()
    ->json();

return response()->json(["reply" => $res["response"]]);

const r = await fetch("https://masarroute.com/api/v1/chat", {
  method: "POST",
  headers: { "X-API-Key": "sk_live_...", "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Hello" }],
  }),
});
const data = await r.json();
if (!r.ok) throw new Error(data.code || "request failed");
console.log(data.response, data.usage.total_tokens);

import requests

r = requests.post(
    "https://masarroute.com/api/v1/chat",
    headers={"X-API-Key": "sk_live_..."},
    json={"model": "gpt-4o-mini",
          "messages": [{"role": "user", "content": "Hello"}]},
    timeout=60,
)
r.raise_for_status()
data = r.json()
print(data["response"], data["usage"]["total_tokens"])

3. المصادقة

بوابتان تفتحان كل استدعاء: باقة رصيد فعّالة (وإلا 402 ‏NO_AI_PLAN) وحصة متبقية (وإلا 429 ‏AI_QUOTA_EXHAUSTED). المفاتيح تُخزَّن مُجزّأة — أنشئ واحداً وانسخه مرة واحدة، ثم دوّر بدل استرجاعه.

4. النماذج والأسعار live

الأسعار بالدولار لكل مليون توكن، تُجلب من المزود الخارجي مع كل مزامنة وتُحوَّل إلى عملة المنصة. السعر النهائي يحمل عمولة المنصة وهامش الربح معاً — ما تراه هو ما يُخصم من المستدعي، للدخل والخرج على حدة.

5. باقات الرصيد live

باقات AI هي باقات رصيد لا اشتراكات شهرية: تشتري حزمة من التوكنات والطلبات، فتُستهلك مع استدعاءاتك — وتمتد حتى تُستهلك كاملاً، ولا تنتهي بمرور التقويم. وعند نفاد حصة التوكنات أو الطلبات تتوقف الاستدعاءات بـ AI_QUOTA_EXHAUSTED حتى التفعة التالية.

• الباقات المجانية تتفعّل فوراً؛ والمدفوعة تعود بـ PAYMENT_REQUIRED حتى يتأكد الدفع.
• ‏GET /api/v1/ai/subscription تعيد الباقة الفعّالة مع tokens_used / tokens_limit وrequests_used / requests_limit.
• تبديل الباقة يبدأ رصيداً جديداً — وحصة الباقة الجديدة تحل محلها فوراً.
• قائمة الباقات كاملة بأسعارها في صفحة أسعار AI.

6. المفاتيح والاستهلاك

7. رموز الأخطاء

8. فهرس المسارات الكامل 31

كل عملية AI تُسجّل فعلاً في البوابة. الصفوف لغتها محايدة عن قصد: الطريقة والمسار وبيان الدخول المطلوب.

واجهة نماذج AI 14

الإدارة — AI 16

9. قواعد الأمان

1. خزّن مفاتيح sk_ في Secret Manager أو متغير بيئة على الخادم — لا في المستودع أبداً ولا في حزمة متصفح.
2. مفتاح sk_ واحد لكل بيئة أو مستأجر — تعزل المستدعرين حتى لا يستهلك تسريب واحد رصيدك كله.
3. دوّر فور أي تسريب مشتبه به (POST /api/v1/ai/keys/{id}/rotate) — المفتاح القديم يموت فوراً.
4. راقب last_used_at لكل مفتاح؛ منطقة أو حجم غير متوقع هو أول إشارة تسريب.
5. مفتاح المزود الخارجي لا يغادر المنصة ولا يظهر في أي رد — ولا تطلبه من مستخدميك أبداً.
6. تفرّع على body.code والتزم بـ Retry-After في 429؛ ولا تُعد المحاولة بعد المهلة عشوائياً — الاستهلاك يُحتسب لكل استدعاء.
7. الدعم يطلب request_id ورمز الخطأ — ولا يطلب مفتاحاً أبداً. ومن يطلب مفتاحاً بأي قناة فهو مهاجم.