XUSS AI API

یک API آمادهٔ تولید سازگار با OpenAI روی پلتفرم میزبانی XUSS. هر SDK، ویرایشگر یا کلاینت چت OpenAI را به XUSS وصل کنید — بدون قفل شدن به یک فروشنده، یک کلید، و پرداخت به‌ازای مصرف از موجودی XUSS.

• آدرس پایه: https://xuss.us/v1
• احراز هویت: Authorization: Bearer xsk-… (در پنل یک کلید بسازید)
• پنل: https://xuss.us/panel/api
• قالب: OpenAI Chat Completions (استریم، ابزارها، بینایی، حالت JSON)

شروع سریع

۱. یک کلید API بسازید در پنل: API → کلیدهای API → ساخت کلید. آن را کپی کنید — فقط یک‌بار نمایش داده می‌شود. کلیدها با xsk- شروع می‌شوند.

۲. API را فراخوانی کنید به هر زبانی — یک تب انتخاب کنید:

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- و سپس یک رشتهٔ تصادفی طولانی است. فقط چند حرف اول برای نمایش ذخیره می‌شود؛ مقدار کامل یک‌بار در زمان ساخت نشان داده می‌شود.
• حداکثر ۱۰ کلید فعال برای هر حساب.
• هر کلید می‌تواند یک تاریخ انقضا و یک سقف هزینه (دلار) اختیاری داشته باشد. وقتی کلید منقضی شود یا به سقف برسد، درخواست‌ها با 401 (key_expired) یا 402 (key_spend_limit_reached) رد می‌شوند تا کلید تازه بسازید یا سقف را بالا ببرید.
• ساخت کلید در پنل با Cloudflare Turnstile (کپچا) محافظت می‌شود، پس کلیدها با اسکریپت ساخته نمی‌شوند.
• باطل کردن کلید فوراً اعمال می‌شود.
• کلیدها دسترسی حساب شما به AI API را به ارث می‌برند. اگر API برای حساب شما فعال نباشد، درخواست‌ها 403 برمی‌گردانند.

هرگز کلید را در کد سمت کلاینت یا مخازن عمومی افشا نکنید. اگر کلید لو رفت، در پنل باطلش کنید و کلید تازه بسازید.

نقاط پایانی

همه Authorization: Bearer xsk-… را می‌پذیرند.

مدل‌ها

GET /v1/models مدل‌های ارائه‌شده در API را همراه با پنجرهٔ زمینه، پشتیبانی بینایی و قیمت هر توکن برمی‌گرداند:

{
  "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
      }
    }
  ]
}

قیمت‌ها دلار به‌ازای هر توکن هستند. برای قیمت هر میلیون (مثل پنل) در ۱٬۰۰۰٬۰۰۰ ضرب کنید.

مسیریابی مدل. پشت یک شناسهٔ مدل، 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 داشته باشند. SDKهای استاندارد آن را نادیده می‌گیرند و لازم نیست آن را به‌عنوان خروجی پردازش کنید.

پرامپت‌های سیستمی و هویت

پیام‌های system شما محترم شمرده می‌شوند. مدل همچنین نام نمایشی خود را می‌داند و وقتی پرسیده شود کدام مدل است، تنها با همان نام پاسخ می‌دهد — هرگز هیچ ارائه‌دهنده یا مسیر بالادستی را فاش نمی‌کند.

{
  "model": "xuss/kitsune",
  "messages": [
    {"role": "system", "content": "تو یک دستیار موجز DevOps هستی. با بولت پاسخ بده."},
    {"role": "user", "content": "چگونه یک سرویس systemd را ری‌استارت کنم؟"}
  ]
}

بینایی (تصاویر)

تصاویر را به‌صورت بخش‌های محتوای image_url سبک OpenAI بفرستید (data URL یا URLهای عمومی 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..."}},
        ],
    }],
)

محدودیت‌ها: حداکثر ۸ بخش تصویر، هرکدام تا ~۶ مگابایت؛ تصاویر در بودجهٔ متنی حساب نمی‌شوند.

فراخوانی توابع

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، پایگاه‌داده و غیره) در دست خودتان می‌مانند و عمداً ارائه نشده‌اند.

• بدون استریم: سرور حلقهٔ ابزار (تا ۶ دور) را اجرا می‌کند و پاسخ نهایی را برمی‌گرداند؛ 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 در پنل هزینه، درخواست‌ها، توکن‌ها، تفکیک بر اساس مدل و کلید و لاگ تماس‌های اخیر را با بازه‌های قابل‌انتخاب (امروز، ۷/۳۰/۹۰ روز، این/ماه گذشته، همه) نشان می‌دهد.
• درخواست‌ها وقتی موجودی کافی نباشد با 402 رد می‌شوند.

فرمول هزینه (هر درخواست):

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

(قیمت‌ها به‌ازای هر توکن؛ برای قیمت هر میلیون بر ۱٬۰۰۰٬۰۰۰ تقسیم کنید.)

محدودیت نرخ و سهمیه‌ها

عبور از حد، 429 با معنای Retry-After برمی‌گرداند (عقب‌نشینی و تلاش مجدد). بدنهٔ درخواست تا ۲۵ مگابایت محدود است.

خطاها

خطاها از قالب خطای OpenAI پیروی می‌کنند:

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

param وقتی تنظیم می‌شود که خطا مربوط به یک فیلد مشخص درخواست باشد. SDKهای استاندارد 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
• تیکت‌ها و پشتیبانی تلگرام از داشبورد پنل شما
• ایمیل: support@xuss.us