XUSS AI API

Продакшн-API, совместимый с OpenAI, поверх хостинг-платформы XUSS. Подключите любой OpenAI SDK, редактор или чат-клиент к XUSS — без привязки к вендору, один ключ, оплата по мере использования с вашего баланса XUSS.

• Базовый URL: https://xuss.us/v1
• Авторизация: Authorization: Bearer xsk-… (создайте ключ в панели)
• Панель: https://xuss.us/panel/api
• Формат: OpenAI Chat Completions (стриминг, инструменты, зрение, JSON-режим)

Быстрый старт

1. Создайте API-ключ в панели: API → API-ключи → Создать ключ. Скопируйте его — он показывается только один раз. Ключи начинаются с xsk-.

2. Вызовите 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-, за которым следует длинная случайная строка. Для отображения хранятся только первые символы; полное значение показывается один раз при создании.
• До 10 активных ключей на аккаунт.
• У каждого ключа может быть необязательная дата истечения и необязательный лимит расходов (USD). Когда ключ истекает или достигает лимита, запросы с ним отклоняются с 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
      }
    }
  ]
}

Цены указаны в USD за токен. Умножьте на 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. Стандартные SDK его игнорируют, и его не нужно обрабатывать как вывод.

Системные промпты и идентичность

Ваши сообщения system учитываются. Модель также знает своё отображаемое имя и, когда её спрашивают, какая она модель, отвечает только этим именем — она никогда не раскрывает вышестоящего провайдера или маршрут.

{
  "model": "xuss/kitsune",
  "messages": [
    {"role": "system", "content": "Ты лаконичный DevOps-ассистент. Отвечай пунктами."},
    {"role": "user", "content": "Как перезапустить сервис systemd?"}
  ]
}

Зрение (изображения)

Передавайте изображения как части контента OpenAI image_url (data URL или публичные http(s) URL). Изображения принимают только модели с "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 устанавливается, когда ошибка касается конкретного поля запроса. Стандартные SDK читают error.message (и error.code) напрямую.

Временные сбои также приходят как обычное сообщение ассистента, начинающееся с «The model is temporarily unavailable…», если поток уже начался.

Использование с OpenAI-совместимыми инструментами

Работает любой клиент с поддержкой пользовательского базового URL OpenAI. Укажите:

• Базовый URL: 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.

FAQ

Нужна ли отдельная подписка? Нет. Вы платите за токены со своего баланса XUSS.

Какие id моделей использовать? Ровно те, что в GET /v1/models (например, xuss/kitsune). Отображаемые имена вроде «Kitsune» показаны в панели.

Можно ли отправлять изображения? Да, моделям с "vision": true.

Используются ли мои данные для обучения? Нет — запросы проксируются к модели для получения ответа и не используются для обучения.

Что если провайдер медленный или недоступен? Запрос прозрачно повторяется на альтернативных мощностях; id модели и цены сохраняются.

Как сменить ключ? Создайте новый ключ, переключите приложения, затем отзовите старый в панели.

Поддержка

• Панель: https://xuss.us/panel/api
• Тикеты и поддержка в Telegram из дашборда панели
• Email: support@xuss.us