XUSS AI API

واجهة برمجية جاهزة للإنتاج متوافقة مع OpenAI فوق منصة الاستضافة XUSS. استخدم أي مجموعة أدوات OpenAI أو محرر أو تطبيق محادثة ووجّهه إلى XUSS — بلا ارتباط بمزوّد، مفتاح واحد، ودفع حسب الاستخدام من رصيد XUSS.

• عنوان الأساس: https://xuss.us/v1
• المصادقة: Authorization: Bearer xsk-… (أنشئ مفتاحًا في اللوحة)
• اللوحة: https://xuss.us/panel/api
• الصيغة: OpenAI Chat Completions (البث، الأدوات، الرؤية، وضع JSON)

البدء السريع

1. أنشئ مفتاح API في اللوحة: API → مفاتيح API → إنشاء مفتاح. انسخه — يُعرض مرة واحدة فقط. تبدأ المفاتيح بـ xsk-.

2. استدعِ الواجهة من أي لغة — اختر تبويبًا:

curl https://xuss.us/v1/chat/completions \
  -H "Authorization: Bearer xsk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xuss/kitsune",
    "messages": [{"role": "user", "content": "مرحبًا!"}]
  }'

from openai import OpenAI

client = OpenAI(base_url="https://xuss.us/v1", api_key="xsk-YOUR_KEY")

r = client.chat.completions.create(
    model="xuss/kitsune",
    messages=[{"role": "user", "content": "مرحبًا!"}],
)
print(r.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://xuss.us/v1", apiKey: "xsk-YOUR_KEY" });

const r = await client.chat.completions.create({
  model: "xuss/kitsune",
  messages: [{ role: "user", content: "مرحبًا!" }],
});
console.log(r.choices[0].message.content);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{"model":"xuss/kitsune","messages":[{"role":"user","content":"مرحبًا!"}]}`)
	req, _ := http.NewRequest("POST", "https://xuss.us/v1/chat/completions", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer xsk-YOUR_KEY")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

<?php
$ch = curl_init('https://xuss.us/v1/chat/completions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer xsk-YOUR_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'xuss/kitsune',
        'messages' => [['role' => 'user', 'content' => 'مرحبًا!']],
    ]),
]);
$res = json_decode(curl_exec($ch), true);
echo $res['choices'][0]['message']['content'], PHP_EOL;

هذا كل شيء — يُخصم من رصيد XUSS لكل رمز، دون اشتراك.

المصادقة

كل طلب يحتاج رمز bearer:

Authorization: Bearer xsk-YOUR_KEY
Content-Type: application/json

تُنشأ المفاتيح وتُلغى في اللوحة → API. القواعد:

• المفتاح يبدأ بـ xsk- متبوعًا بسلسلة عشوائية طويلة. تُخزَّن الأحرف الأولى فقط للعرض؛ وتُعرض القيمة الكاملة مرة واحدة عند الإنشاء.
• حتى 10 مفاتيح نشطة لكل حساب.
• يمكن أن يحمل كل مفتاح تاريخ انتهاء اختياريًا وحد إنفاق اختياريًا (بالدولار). عند انتهاء صلاحية المفتاح أو بلوغه الحد، تفشل الطلبات به بـ 401 (key_expired) أو 402 (key_spend_limit_reached) حتى تنشئ مفتاحًا جديدًا أو ترفع الحد.
• إنشاء مفتاح في اللوحة محميّ بـ Cloudflare Turnstile (اختبار كابتشا)، لذا لا يمكن توليد المفاتيح عبر سكربتات.
• إلغاء المفتاح يبدأ فورًا.
• ترث المفاتيح وصول حسابك إلى AI API. إذا لم تكن الواجهة مفعّلة لحسابك، تُرجع الطلبات 403.

لا تُظهر المفتاح أبدًا في كود العميل أو مستودعات عامة. إذا تسرّب مفتاح، ألغِه في اللوحة وأنشئ آخر.

نقاط النهاية

جميعها تقبل Authorization: Bearer xsk-….

النماذج

تُرجع GET /v1/models النماذج المتاحة في الواجهة، مع نافذة السياق ودعم الرؤية والسعر لكل رمز:

{
  "object": "list",
  "data": [
    {
      "id": "xuss/kitsune",
      "object": "model",
      "owned_by": "xuss",
      "context_window": 1048576,
      "vision": true,
      "pricing": {
        "prompt": 0.00000029,
        "completion": 0.00000129,
        "input_cache_read": 0.0000000099
      }
    }
  ]
}

الأسعار بالدولار لكل رمز. اضرب في 1,000,000 للحصول على السعر لكل مليون كما في اللوحة.

توجيه النموذج. خلف معرّف نموذج واحد، قد يوجّه XUSS الطلبات إلى قدرات مختلفة ليبقى الخدمة سريعة ومتاحة. هذا غير ظاهر لك: النموذج model المطلوب هو نفسه المُعاد في الرد، والنموذج يعرف اسمه. الأسعار في /v1/models هي الأسعار التي تُحاسَب بها.

إكمال المحادثة

POST /v1/chat/completions

جسم الطلب

messages يتبع مخطط OpenAI (أدوار system، user، assistant، tool؛ مصفوفات محتوى متعددة الوسائط).

الرد

{
  "id": "chatcmpl-3f9c1a...",
  "object": "chat.completion",
  "created": 1791000000,
  "model": "xuss/kitsune",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "مرحبًا! كيف أساعدك؟"},
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 7, "total_tokens": 19},
  "system_fingerprint": "xuss"
}

finish_reason هو stop أو length أو tool_calls.

Messages

مصفوفة رسائل OpenAI قياسية. طلب أدنى بدورة واحدة:

{"model": "xuss/kitsune", "messages": [{"role": "user", "content": "مرحبًا"}]}

محادثة متعددة الأدوار — أرسل السجل كاملًا في كل مرة:

{
  "model": "xuss/kitsune",
  "messages": [
    {"role": "system", "content": "أنت مساعد موجز."},
    {"role": "user", "content": "ما هو XUSS؟"},
    {"role": "assistant", "content": "XUSS منصة استضافة."},
    {"role": "user", "content": "هل لديها AI API؟"}
  ]
}

البث

اضبط "stream": true لاستقبال Server-Sent Events. كل سطر هو data: {json}؛ وينتهي البث بـ data: [DONE].

تبدو الأجزاء هكذا:

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":…,"model":"xuss/kitsune","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"system_fingerprint":"xuss"}

data: {"id":"chatcmpl-…","choices":[{"index":0,"delta":{"content":"صمت "},"finish_reason":null}]}

data: {"id":"chatcmpl-…","choices":[{"index":0,"delta":{"content":"الخوادم "},"finish_reason":null}]}

data: {"id":"chatcmpl-…","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":9,"total_tokens":23}}

data: [DONE]

اقرأ البث بأي لغة:

curl -N https://xuss.us/v1/chat/completions \
  -H "Authorization: Bearer xsk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"xuss/kitsune","stream":true,
       "messages":[{"role":"user","content":"اكتب هايكو عن الخوادم"}]}'

stream = client.chat.completions.create(
    model="xuss/kitsune",
    messages=[{"role": "user", "content": "اكتب هايكو عن الخوادم"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content if chunk.choices else None
    if delta:
        print(delta, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "xuss/kitsune",
  messages: [{ role: "user", content: "اكتب هايكو عن الخوادم" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

package main

import (
	"bufio"
	"bytes"
	"fmt"
	"net/http"
	"strings"
)

func main() {
	body := []byte(`{"model":"xuss/kitsune","stream":true,"messages":[{"role":"user","content":"اكتب هايكو عن الخوادم"}]}`)
	req, _ := http.NewRequest("POST", "https://xuss.us/v1/chat/completions", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer xsk-YOUR_KEY")
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	sc := bufio.NewScanner(res.Body)
	for sc.Scan() {
		line := sc.Text()
		if !strings.HasPrefix(line, "data: ") || strings.HasSuffix(line, "[DONE]") {
			continue
		}
		fmt.Println(line[6:]) // parse JSON, read choices[0].delta.content
	}
}

<?php
$ch = curl_init('https://xuss.us/v1/chat/completions');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer xsk-YOUR_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'xuss/kitsune',
        'stream' => true,
        'messages' => [['role' => 'user', 'content' => 'اكتب هايكو عن الخوادم']],
    ]),
    CURLOPT_WRITEFUNCTION => function ($ch, $chunk) {
        foreach (explode("\n", $chunk) as $line) {
            if (str_starts_with($line, 'data: ') && !str_contains($line, '[DONE]')) {
                $j = json_decode(substr($line, 6), true);
                echo $j['choices'][0]['delta']['content'] ?? '';
            }
        }
        return strlen($chunk);
    },
]);
curl_exec($ch);

عندما يدعم النموذج التفكير، قد تحمل أجزاء البث حقلًا إضافيًا reasoning_content داخل delta. تتجاهله مجموعات أدوات OpenAI القياسية ولا يلزمك معالجته كمخرَج.

موجهات النظام والهوية

تُحترم رسائل system الخاصة بك. ويعرف النموذج أيضًا اسمه المعروض، وعند سؤاله عن أي نموذج هو يجيب بذلك الاسم فقط — ولا يكشف أبدًا أي مزوّد أو مسار أعلى.

{
  "model": "xuss/kitsune",
  "messages": [
    {"role": "system", "content": "أنت مساعد DevOps موجز. أجب بنقاط."},
    {"role": "user", "content": "كيف أعيد تشغيل خدمة systemd؟"}
  ]
}

الرؤية (الصور)

مرّر الصور كأجزاء محتوى image_url بنمط OpenAI (عناوين data أو عناوين http(s) عامة). تقبل الصور فقط النماذج التي لديها "vision": true في /v1/models؛ وإرسال صورة إلى نموذج بلا رؤية يُرجع ملاحظة نصية ويجيب النموذج على النص فقط.

r = client.chat.completions.create(
    model="xuss/kitsune",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "ماذا يوجد في هذه الصورة؟"},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}},
        ],
    }],
)

الحدود: حتى 8 أجزاء صور، كل منها حتى ~6 ميغابايت؛ لا تُحسب الصور ضمن ميزانية النص.

استدعاء الدوال

مرّر tools بنمط OpenAI. عندما يقرر النموذج استدعاء دالة، يصبح finish_reason هو tool_calls وتحتوي الرسالة على tool_calls.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

r = client.chat.completions.create(
    model="xuss/kitsune",
    messages=[{"role": "user", "content": "الطقس في طشقند؟"}],
    tools=tools,
)

call = r.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)

ثم أرسل النتيجة كرسالة tool:

messages = [
    {"role": "user", "content": "الطقس في طشقند؟"},
    r.choices[0].message,
    {"role": "tool", "tool_call_id": call.id, "content": '{"temp_c": 24, "sky": "clear"}'},
]
final = client.chat.completions.create(model="xuss/kitsune", messages=messages)

أدوات الخادم (الويب + المهارات)

تفعيلها لكل طلب. أضف "xuss_tools": true (كلها) أو مصفوفة بالتي تريدها. حينها يشغّل XUSS هذه الأدوات نيابةً عنك على الخادم — يستدعيها النموذج، وينفّذها الخادم ويكمل، فتحصل على الجواب النهائي في الرد نفسه. لا حاجة إلى حلقة في جهة العميل.

r = client.chat.completions.create(
    model="xuss/kitsune",
    xuss_tools=True,                       # أو ["web_search", "read_skill"]
    messages=[{"role": "user",
               "content": "ابحث في الويب عن أحدث إصدار لـ Python ولخّصه."}],
)
print(r.choices[0].message.content)

{
  "model": "xuss/kitsune",
  "xuss_tools": true,
  "messages": [{"role": "user", "content": "افتح https://example.com وأعطني عنوان الصفحة."}]
}

هذه للقراءة فقط: لا وصول إلى الملفات أو قواعد البيانات أو الاستضافات أو حسابك. الأدوات التي تغيّر شيئًا (إدارة الملفات، DNS، قواعد البيانات، وما إلى ذلك) تبقى بين يديك ولا تُتاح عن قصد.

• بدون بث: يشغّل الخادم حلقة الأدوات (حتى 6 جولات) ويعيد الجواب النهائي؛ ويغطي usage (والفوترة) كل جولة.
• مع البث ("stream": true): تعمل الأدوات على الخادم، ثم يُبَث الجواب النهائي كـ SSE كالمعتاد.
• إذا أرسلت أيضًا tools الخاصة بك، يمكن للنموذج استدعاء الاثنين — ينفّذ XUSS أدواته ويعيد استدعاء أداتك عبر tool_calls لتنفيذه (السلوك القياسي).
• تعرّف عليها وقت التشغيل: GET /v1/tools (التعريفات) وGET /v1/skills (القائمة أدناه).

المهارات المتاحة

يحمّل read_skill الوثيقة المرجعية الكاملة لأي منها إلى السياق — فقط أخبر النموذج أيها (مثلًا "استخدم مهارة product-design").

المخرَج المنظَّم (وضع JSON)

اضبط response_format على {"type":"json_object"} واطلب من النموذج إخراج JSON. يكون content في الرد سلسلة JSON.

r = client.chat.completions.create(
    model="xuss/kitsune",
    response_format={"type": "json_object"},
    messages=[{"role": "user",
               "content": "أعد JSON بالمفتاحين a و b، a=1، b=2"}],
)
import json
print(json.loads(r.choices[0].message.content))  # {'a': 1, 'b': 2}

حلّل دائمًا بشكل دفاعي وصف الشكل الدقيق المطلوب في الموجه.

الفوترة وحساب الرموز

• تُخصم الرسوم من رصيد XUSS (يمكن التعبئة من اللوحة).
• تُحاسَب لكل رمز بسعر API للنموذج: الإدخال (فشل الكاش)، إصابة الكاش (أرخص حيث مدعومة)، والإخراج.
• يُبلّغ usage في كل طلب عن prompt_tokens وcompletion_tokens وtotal_tokens.
• تعرض صفحة API في اللوحة الإنفاق والطلبات والرموز وتوزيعًا حسب النموذج والمفتاح وسجل المكالمات الأخيرة، مع نطاقات قابلة للاختيار (اليوم، 7/30/90 يومًا، هذا/الشهر الماضي، كل الأوقات).
• تُرفض الطلبات بـ 402 عندما يكون رصيدك غير كافٍ.

صيغة التكلفة (لكل طلب):

cost = cache_miss_tokens × price_in
     + cache_hit_tokens  × price_cache
     + completion_tokens × price_out

(الأسعار لكل رمز؛ اقسم على 1,000,000 للسعر لكل مليون.)

حدود المعدل والحصص

تجاوز الحد يُرجع 429 بدلالة Retry-After (تراجع ثم أعد المحاولة). جسم الطلب محدود بـ 25 ميغابايت.

الأخطاء

تتبع الأخطاء صيغة خطأ OpenAI:

{
  "error": {
    "message": "Model 'xuss/foo' not found",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

يُضبط param عندما يتعلق الخطأ بحقل طلب محدّد. تقرأ مجموعات أدوات OpenAI القياسية error.message (وerror.code) مباشرة.

تُسلَّم الإخفاقات المؤقتة أيضًا كرسالة مساعد عادية تبدأ بـ "The model is temporarily unavailable…" عندما يكون البث قد بدأ بالفعل.

الاستخدام مع أدوات متوافقة مع OpenAI

يعمل أي عميل يدعم عنوان أساس OpenAI مخصصًا. اضبط:

• عنوان الأساس: https://xuss.us/v1
• مفتاح API: مفتاحك xsk-…
• النموذج: مثلًا xuss/kitsune

أمثلة:

# open-webui / LibreChat / Cursor / Cline / Continue / LangChain:
#   set the OpenAI base URL to https://xuss.us/v1 and paste your key

نمط متغيرات البيئة (تحترمه أدوات كثيرة):

export OPENAI_BASE_URL="https://xuss.us/v1"
export OPENAI_API_KEY="xsk-YOUR_KEY"

LangChain (Python):

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="xuss/kitsune", base_url="https://xuss.us/v1",
                 api_key="xsk-YOUR_KEY")
print(llm.invoke("مرحبًا").content)

المعاملات المتقدمة

تُقبل وتُمرَّر إلى النموذج عند دعمها: top_p، stop، seed، presence_penalty، frequency_penalty، logit_bias، user، n، parallel_tool_calls، tool_choice.

الأسئلة الشائعة

هل أحتاج اشتراكًا منفصلًا؟ لا. تدفع لكل رمز من رصيد XUSS.

أي معرّفات نماذج أستخدم؟ تمامًا تلك الموجودة في GET /v1/models (مثل xuss/kitsune). تُعرض الأسماء مثل "Kitsune" في اللوحة.

هل يمكنني إرسال صور؟ نعم، إلى النماذج المعلّمة بـ "vision": true.

هل تُستخدم بياناتي للتدريب؟ لا — تُمرَّر الطلبات إلى النموذج لإنتاج جوابك ولا تُستخدم للتدريب.

ماذا يحدث إذا كان المزوّد بطيئًا أو متوقفًا؟ يُعاد الطلب بشفافية على قدرات بديلة؛ وتبقى معرّف النموذج والسعر كما هما.

كيف أبدّل مفتاحًا؟ أنشئ مفتاحًا جديدًا، وحوّل تطبيقاتك إليه، ثم ألغِ القديم في اللوحة.

الدعم

• اللوحة: https://xuss.us/panel/api
• التذاكر ودعم Telegram من لوحة تحكم حسابك
• البريد: support@xuss.us