الوثائق

الواجهة، على المسارين

كل ما هنا ينطبق على المسارين. ولكل مسار صفحته بنماذجه وأسعاره وأمثلته.

سيادي · داخل المملكة فقطhttps://inference.sigmix.sa/ksa-sovereign-route-only/v1

النماذج والأسعار والأمثلة

دوليhttps://inference.sigmix.sa/international-route-only/v1

النماذج والأسعار والأمثلة

المصادقة

مفاتيح Bearer

أرسل المفتاح في الترويسة Authorization: Bearer متبوعة بالمفتاح. ويُقبل x-api-key أيضاً للمكتبات التي ترسله.

مسار واحد لكل مفتاح

تبدأ المفاتيح السيادية بـ sgx-ksa- والدولية بـ sgx-intl-. يُرفض المفتاح على مسار الآخر بالرمز wrong_route.

يظهر مرة واحدة

نحتفظ ببصمة لكل مفتاح لا بالمفتاح نفسه. ويسري الإلغاء من الطلب التالي.

Authorization: Bearer sgx-ksa-…      # sovereign key
Authorization: Bearer sgx-intl-…     # international key

التوافق مع OpenAI

تتبع صيغ الطلبات والاستجابات صيغ OpenAI، فتعمل المكتبات الرسمية بتغيير base_url وapi_key.

نقاط الوصول

chat/completions وembeddings وaudio/speech وaudio/transcriptions وaudio/translations وimages/generations، وGET models.

ترويسات الاستجابة

x-request-id في كل استجابة؛ وx-sigmix-route؛ وx-sigmix-charge-usd بالمبلغ الدقيق في الاستجابات غير المتدفقة (ويظهر مبلغ البث في صفحة الاستهلاك)؛ وx-sigmix-max-tokens-clamped عندما يتجاوز max_tokens حد النموذج.

معرّفات النماذج

استخدم المعرّف من قائمة نماذج المسار أو GET /v1/models. قد يوجد المعرّف نفسه على المسارين بوصفهما نموذجين منفصلين بسعرين.

غير مدعوم بعد

واجهتا Responses وAssistants، ورفع الملفات، والضبط الدقيق. تعمل روابط الصور في المحادثة حيث يجلبها النموذج؛ وتقبل بعض النماذج الدولية روابط base64 فقط.

البث

stream: true في المحادثة يُرجع أحداثاً متدفقة بصيغة OpenAI وتنتهي بـ data: [DONE].

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

الأخطاء

تتبع الأخطاء صيغة OpenAI مع رمز يوضح من المسؤول. ولا يُحتسب أي طلب فشل.

{
  "error": {
    "message": "Your available balance does not cover this request…",
    "type": "insufficient_quota",
    "code": "insufficient_credit",
    "param": null,
    "request_id": "6f0c…"
  }
}

HTTP	الرمز	المسؤول	المعنى	ما العمل
401	`invalid_api_key`	من جهتك	المفتاح مفقود أو بصيغة خاطئة أو غير معروف أو ملغى.	أرسل Authorization: Bearer مع مفتاح صالح من لوحة التحكم.
403	`wrong_route`	من جهتك	المفتاح يخص المسار الآخر.	استخدم المفتاح على مساره، أو أنشئ مفتاحاً لهذا المسار.
403	`account_suspended`	من جهتك	الحساب معلّق أو مغلق.	تواصل معنا.
400	`invalid_request`	من جهتك	جسم الطلب غير صحيح أو أحد الحقول غير صالح.	راجع error.param وerror.message.
404	`unknown_endpoint`	من جهتك	لا توجد نقطة وصول بهذا العنوان.	طابق العنوان مع جدول نقاط الوصول.
404	`model_not_found`	من جهتك	هذا النموذج غير منشور على هذا المسار.	GET /v1/models يعرض المتاح.
403	`model_not_allowed`	من جهتك	المفتاح مقصور على نماذج أخرى.	عدّل النماذج المسموح بها للمفتاح.
400	`modality_mismatch`	من جهتك	يُستدعى النموذج على نقطة وصول أخرى.	استخدم نقطة الوصول المذكورة في الرسالة.
413	`payload_too_large`	من جهتك	الجسم يتجاوز ١٦ م.ب أو الملف الصوتي يتجاوز ٢٥ م.ب.	أرسل أقل، أو قسّم الملف الصوتي.
402	`insufficient_credit`	من جهتك	رصيدك المتاح لا يغطي أقصى تكلفة ممكنة لهذا الطلب.	أضف رصيداً، أو قلّل max_tokens.
402	`paid_credit_required`	من جهتك	لا يمكن الدفع لهذا النموذج برصيد التجربة المجانية، ورصيدك المدفوع لا يغطي أقصى تكلفة ممكنة للطلب.	اشحن رصيدك، أو استخدم نموذجاً مشمولاً في التجربة المجانية.
403	`streaming_not_allowed`	من جهتك	البث معطّل لهذا المفتاح أو الحساب، أو الرصيد دون الحد الأدنى.	أرسل بدون stream: true، أو أضف رصيداً.
429	`rate_limited`	من جهتك	طلبات كثيرة هذه الدقيقة لهذا المفتاح.	انتظر عدد الثواني في Retry-After.
429	`concurrency_limit`	من جهتك	طلبات متزامنة كثيرة لهذا المفتاح.	انتظر انتهاء أحدها، أو ارفع حد المفتاح.
429	`spend_cap_reached`	من جهتك	بلغت سقفاً يومياً أو شهرياً أو للطلب الواحد حددته بنفسك.	ارفع السقف على المفتاح، أو انتظر الفترة التالية.
503	`gateway_disabled`	متوقف	أوقف المشغّل الواجهة مؤقتاً.	أعد المحاولة بعد Retry-After؛ راجع صفحة الحالة.
503	`route_disabled`	متوقف	أوقف المشغّل هذا المسار مؤقتاً.	أعد المحاولة لاحقاً. لا يُنقل الطلب السيادي إلى المسار الآخر.
503	`modality_disabled`	متوقف	أوقف المشغّل نقطة الوصول هذه مؤقتاً.	أعد المحاولة لاحقاً.
503	`model_disabled`	متوقف	أوقف المشغّل هذا النموذج مؤقتاً.	أعد المحاولة لاحقاً، أو استخدم نموذجاً آخر.
503	`capacity_exhausted`	من جهتنا	كل نقاط الخدمة لهذا النموذج مشغولة.	أعد المحاولة بعد لحظة.
503	`upstream_unavailable`	من جهتنا	لا توجد نقطة على هذا المسار تخدم النموذج الآن.	أعد المحاولة؛ راجع صفحة الحالة.
504	`upstream_timeout`	من جهتنا	لم يُجب النموذج في الوقت المحدد.	أعد المحاولة، أو قلّل max_tokens.
502	`upstream_error`	من جهتنا	أخفقت نقطة النموذج.	أعد المحاولة. لا يُحتسب.
400	`upstream_rejected`	من جهتك	رفض النموذج الطلب — طويل جداً أو معامل غير مدعوم. تُنقل حالته ورسالته كما هي.	اقرأ الرسالة؛ اختصر الطلب أو عدّله.
504	`deadline_exceeded`	من جهتك	بلغ الطلب حدّه الأقصى (15 دقيقة). تتوقف الإجابة المتدفقة عنده ولا يُحتسب إلا ما وُلّد منها، والطلب الذي لم تبدأ إجابته لا يُحتسب.	قلّل max_tokens، أو قسّم العمل.
503	`service_restarting`	من جهتنا	كانت الواجهة تُعاد تشغيلها. تتوقف الإجابة المتدفقة الجارية ولا يُحتسب إلا ما وُلّد منها، والطلب الذي لم يبدأ لا يُحتسب.	أعد المحاولة بعد Retry-After.
500	`internal_error`	من جهتنا	حدث عطل من جهتنا.	أعد المحاولة واذكر request_id إن تكرر. لا يُحتسب.

الحدود

المعدل

الطلبات في الدقيقة لكل مفتاح: الحد الافتراضي ما لم تحدد غيره على المفتاح. تجاوزه يُرجع 429 مع Retry-After.

الحجم

أجسام JSON حتى ١٦ م.ب؛ والصوت حتى ٢٥ م.ب؛ وحتى ٨ خيارات (n) لطلب المحادثة و١٠ صور لطلب الصور.

إعادة المحاولة

إن أخفقت نقطة قبل الإجابة تعيد البوابة المحاولة على نقطة أخرى في المسار نفسه. أعد المحاولة بنفسك عند 429 و503 و504، لا عند أخطاء 4xx.

ما الذي نحتفظ به

لكل طلب: الوقت، والمفتاح، والنموذج والمسار، وأعداد الوحدات أو الأحرف أو الثواني أو الصور، والمبلغ، وزمن الاستجابة، والنتيجة. ولا نحتفظ أبداً بالنص أو الإجابة أو الصوت أو الصورة.

على المسار الدولي يعالج المزوّد الذي يُجيب الطلبَ وفق شروطه.