XUSS AI API

API produksi kompatibel OpenAI di atas platform hosting XUSS. Gunakan SDK, editor, atau klien chat OpenAI apa pun dan arahkan ke XUSS — tanpa lock-in vendor, satu kunci, bayar sesuai pemakaian dari saldo XUSS Anda.

• Base URL: https://xuss.us/v1
• Autentikasi: Authorization: Bearer xsk-… (buat kunci di panel)
• Panel: https://xuss.us/panel/api
• Format: OpenAI Chat Completions (streaming, alat, visi, mode JSON)

Mulai cepat

1. Buat kunci API di panel: API → Kunci API → Buat kunci. Salin — hanya ditampilkan sekali. Kunci diawali xsk-.

2. Panggil API dari bahasa apa pun — pilih tab:

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": "Halo!"}]
  }'

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": "Halo!"}],
)
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: "Halo!" }],
});
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":"Halo!"}]}`)
	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' => 'Halo!']],
    ]),
]);
$res = json_decode(curl_exec($ch), true);
echo $res['choices'][0]['message']['content'], PHP_EOL;

Selesai — saldo XUSS Anda ditagih per token, tanpa langganan.

Autentikasi

Setiap permintaan memerlukan token bearer:

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

Kunci dibuat dan dicabut di Panel → API. Aturan:

• Kunci berupa xsk- diikuti string acak panjang. Hanya karakter pertama yang disimpan untuk tampilan; nilai lengkap ditampilkan sekali saat dibuat.
• Hingga 10 kunci aktif per akun.
• Setiap kunci dapat memiliki tanggal kedaluwarsa opsional dan batas belanja opsional (USD). Saat kunci kedaluwarsa atau mencapai batasnya, permintaan dengannya gagal dengan 401 (key_expired) atau 402 (key_spend_limit_reached) sampai Anda membuat kunci baru atau menaikkan batasnya.
• Membuat kunci di panel dilindungi Cloudflare Turnstile (captcha), jadi kunci tidak bisa dibuat oleh skrip.
• Mencabut kunci berlaku seketika.
• Kunci mewarisi akses akun Anda ke AI API. Jika API tidak diaktifkan untuk akun Anda, permintaan mengembalikan 403.

Jangan pernah menampilkan kunci di kode sisi klien atau repositori publik. Jika kunci bocor, cabut di panel dan buat yang baru.

Endpoint

Semua menerima Authorization: Bearer xsk-….

Model

GET /v1/models mengembalikan model yang diekspos di API, termasuk jendela konteks, dukungan visi, dan harga per token:

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

Harga dinyatakan dalam USD per token. Kalikan dengan 1.000.000 untuk harga per juta seperti di panel.

Perutean model. Di balik satu id model, XUSS dapat merutekan permintaan ke kapasitas hulu yang berbeda agar layanan tetap cepat dan tersedia. Ini tidak terlihat oleh Anda: model yang diminta selalu yang dikembalikan, dan model mengetahui namanya. Harga di /v1/models adalah harga yang Anda ditagih.

Chat completions

POST /v1/chat/completions

Body permintaan

messages mengikuti skema OpenAI (peran system, user, assistant, tool; array konten multimodal).

Respons

{
  "id": "chatcmpl-3f9c1a...",
  "object": "chat.completion",
  "created": 1791000000,
  "model": "xuss/kitsune",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Halo! Ada yang bisa dibantu?"},
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 7, "total_tokens": 19},
  "system_fingerprint": "xuss"
}

finish_reason adalah stop, length, atau tool_calls.

Messages

Array pesan OpenAI standar. Permintaan satu giliran minimal:

{"model": "xuss/kitsune", "messages": [{"role": "user", "content": "Halo"}]}

Percakapan multi-giliran — kirim riwayat lengkap setiap kali:

{
  "model": "xuss/kitsune",
  "messages": [
    {"role": "system", "content": "Kamu asisten yang ringkas."},
    {"role": "user", "content": "Apa itu XUSS?"},
    {"role": "assistant", "content": "XUSS adalah platform hosting."},
    {"role": "user", "content": "Apakah punya AI API?"}
  ]
}

Streaming

Setel "stream": true untuk menerima Server-Sent Events. Setiap baris adalah data: {json}; stream berakhir dengan data: [DONE].

Chunk-nya seperti ini:

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":"Senap "},"finish_reason":null}]}

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

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

data: [DONE]

Baca stream dalam bahasa apa pun:

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":"Tulis haiku tentang server"}]}'

stream = client.chat.completions.create(
    model="xuss/kitsune",
    messages=[{"role": "user", "content": "Tulis haiku tentang server"}],
    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: "Tulis haiku tentang server" }],
  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":"Tulis haiku tentang server"}]}`)
	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' => 'Tulis haiku tentang server']],
    ]),
    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);

Saat model mendukung penalaran, chunk streaming dapat membawa field tambahan reasoning_content di delta. SDK standar mengabaikannya dan Anda tidak perlu menanganinya sebagai keluaran.

Prompt sistem dan identitas

Pesan system Anda dihormati. Model juga mengetahui nama tampilannya dan, saat ditanya model apa dirinya, menjawab hanya dengan nama itu — tidak pernah mengungkap penyedia atau rute hulu.

{
  "model": "xuss/kitsune",
  "messages": [
    {"role": "system", "content": "Kamu asisten DevOps yang ringkas. Jawab dengan poin."},
    {"role": "user", "content": "Bagaimana cara me-restart layanan systemd?"}
  ]
}

Visi (gambar)

Kirim gambar sebagai bagian konten image_url OpenAI (data URL atau URL http(s) publik). Hanya model dengan "vision": true di /v1/models yang menerima gambar; mengirim gambar ke model tanpa visi mengembalikan catatan teks dan model hanya menjawab berdasarkan teks.

r = client.chat.completions.create(
    model="xuss/kitsune",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Apa isi gambar ini?"},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}},
        ],
    }],
)

Batas: hingga 8 bagian gambar, masing-masing hingga ~6 MB; gambar tidak dihitung ke anggaran teks.

Pemanggilan fungsi

Kirim tools bergaya OpenAI. Saat model memutuskan memanggil fungsi, finish_reason menjadi tool_calls dan pesan berisi 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": "Cuaca di Tashkent?"}],
    tools=tools,
)

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

Lalu kirim hasilnya kembali sebagai pesan tool:

messages = [
    {"role": "user", "content": "Cuaca di Tashkent?"},
    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)

Alat server (web + keterampilan)

Aktif per permintaan. Tambahkan "xuss_tools": true (semua) atau array yang diinginkan. XUSS lalu menjalankan alat tersebut untuk Anda di server — model memanggilnya, server menjalankannya dan melanjutkan, dan Anda mendapat jawaban akhir dalam respons yang sama. Tanpa loop di sisi klien.

r = client.chat.completions.create(
    model="xuss/kitsune",
    xuss_tools=True,                       # atau ["web_search", "read_skill"]
    messages=[{"role": "user",
               "content": "Cari di web rilis Python terbaru dan ringkas."}],
)
print(r.choices[0].message.content)

{
  "model": "xuss/kitsune",
  "xuss_tools": true,
  "messages": [{"role": "user", "content": "Buka https://example.com dan beri judul halamannya."}]
}

Ini hanya-baca: tanpa akses ke berkas, basis data, hosting, atau akun Anda. Alat yang mengubah sesuatu (manajemen berkas, DNS, basis data, dan seterusnya) tetap di tangan Anda dan sengaja tidak diekspos.

• Non-streaming: server menjalankan loop alat (hingga 6 putaran) dan mengembalikan jawaban akhir; usage (dan penagihan) mencakup setiap putaran.
• Streaming ("stream": true): alat dijalankan di server, lalu jawaban akhir di-stream sebagai SSE seperti biasa.
• Jika Anda juga mengirim tools Anda sendiri, model dapat memanggil keduanya — XUSS menjalankan miliknya dan mengembalikan panggilan alat Anda melalui tool_calls untuk Anda jalankan (perilaku standar).
• Temukan saat runtime: GET /v1/tools (definisi) dan GET /v1/skills (daftar di bawah).

Keterampilan yang tersedia

read_skill memuat dokumen referensi lengkap salah satunya ke konteks — cukup beri tahu model yang mana (mis. "gunakan keterampilan product-design").

Keluaran terstruktur (mode JSON)

Setel response_format ke {"type":"json_object"} dan minta model mengeluarkan JSON. content balasan adalah string JSON.

r = client.chat.completions.create(
    model="xuss/kitsune",
    response_format={"type": "json_object"},
    messages=[{"role": "user",
               "content": "Kembalikan JSON dengan kunci a dan b, a=1, b=2"}],
)
import json
print(json.loads(r.choices[0].message.content))  # {'a': 1, 'b': 2}

Selalu parsing secara defensif dan jelaskan bentuk persisnya di prompt.

Penagihan dan penghitungan token

• Biaya dipotong dari saldo XUSS Anda (isi ulang di panel).
• Ditagih per token dengan harga API model: input (cache miss), cache hit (lebih murah bila didukung), dan output.
• usage setiap permintaan melaporkan prompt_tokens, completion_tokens, dan total_tokens.
• Halaman API di panel menampilkan belanja, permintaan, token, rincian per model dan per kunci, serta log panggilan terbaru, dengan rentang pilihan (hari ini, 7/30/90 hari, bulan ini/lalu, sepanjang waktu).
• Permintaan ditolak dengan 402 saat saldo tidak cukup.

Rumus biaya (per permintaan):

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

(Harga per token; bagi 1.000.000 untuk per juta.)

Batas laju dan kuota

Melebihi batas mengembalikan 429 dengan semantik Retry-After (mundur dan coba lagi). Body permintaan dibatasi 25 MB.

Error

Error mengikuti format error OpenAI:

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

param diisi saat error menyangkut field permintaan tertentu. SDK standar membaca error.message (dan error.code) langsung.

Kegagalan sementara juga dikirim sebagai pesan asisten biasa yang diawali "The model is temporarily unavailable…" saat stream sudah dimulai.

Menggunakan dengan alat kompatibel OpenAI

Klien apa pun yang mendukung base URL OpenAI kustom dapat digunakan. Setel:

• Base URL: https://xuss.us/v1
• Kunci API: kunci xsk-… Anda
• Model: mis. xuss/kitsune

Contoh:

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

Gaya variabel lingkungan (banyak alat menghormatinya):

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("Halo").content)

Parameter lanjutan

Berikut diterima dan diteruskan ke model saat didukung: top_p, stop, seed, presence_penalty, frequency_penalty, logit_bias, user, n, parallel_tool_calls, tool_choice.

FAQ

Apakah saya perlu langganan terpisah? Tidak. Anda membayar per token dari saldo XUSS.

Id model mana yang saya gunakan? Persis yang ada di GET /v1/models (mis. xuss/kitsune). Nama tampilan seperti "Kitsune" ditampilkan di panel.

Bisakah saya mengirim gambar? Ya, ke model bertanda "vision": true.

Apakah data saya digunakan untuk pelatihan? Tidak — permintaan diproksikan ke model untuk menghasilkan jawaban Anda dan tidak digunakan untuk pelatihan.

Apa yang terjadi jika penyedia lambat atau mati? Permintaan dicoba ulang secara transparan pada kapasitas alternatif; id model dan harga tetap sama.

Bagaimana cara merotasi kunci? Buat kunci baru, pindahkan aplikasi Anda, lalu cabut kunci lama di panel.

Dukungan

• Panel: https://xuss.us/panel/api
• Tiket & dukungan Telegram dari dasbor panel Anda
• Email: support@xuss.us