Документация

Начало работы

Обзор XelumAI

XelumAI объединяет современные текстовые ИИ-модели в одном интерфейсе. Моделями можно пользоваться в основном чате, проверять их в нейро-тесте или подключать к собственным приложениям через API.

Что доступно

единый чат с выбором основной модели;
каталог моделей с техническими ID и ценами;
нейро-тест для дополнительных моделей;
дашборд с балансом, активностью и журналом запросов;
API для текста, генерации и редактирования изображений.

Начало работы

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

Создайте ключ во вкладке «API-ключи» дашборда, сохраните его и выполните первый запрос. Базовый адрес API — https://xelumai.ru/v1.

from openai import OpenAI

client = OpenAI(
    api_key="xelum_sk_...",
    base_url="https://xelumai.ru/v1",
)

completion = client.chat.completions.create(
    model="gpt-5-nano",
    messages=[
        {
            "role": "user",
            "content": "Привет!",
        }
    ],
)

print(completion.choices[0].message.content)

Перед запуском установите клиент: pip install openai.

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.XELUM_API_KEY,
    baseURL: "https://xelumai.ru/v1"
});

const completion = await client.chat.completions.create({
    model: "gpt-5-nano",
    messages: [
        {
            role: "user",
            content: "Привет!"
        }
    ]
});

console.log(completion.choices[0].message.content);

Перед запуском установите клиент: npm install openai. Выполняйте этот код на сервере, а не в публичном браузерном JavaScript.

curl https://xelumai.ru/v1/chat/completions \
  -H "Authorization: Bearer $XELUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-nano",
    "messages": [
      {
        "role": "user",
        "content": "Привет!"
      }
    ]
  }'

Начало работы

Модели

У каждой модели есть читаемое название и технический ID. В запросах API передавайте именно ID, например gpt-5-nano. Каталог в дашборде также показывает поставщика, тариф и цену за миллион токенов.

Получить доступные модели

from openai import OpenAI

client = OpenAI(
    api_key="xelum_sk_...",
    base_url="https://xelumai.ru/v1",
)

for model in client.models.list().data:
    print(model.id)

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.XELUM_API_KEY,
    baseURL: "https://xelumai.ru/v1"
});

const models = await client.models.list();
for (const model of models.data) {
    console.log(model.id);
}

curl https://xelumai.ru/v1/models \
  -H "Authorization: Bearer $XELUM_API_KEY"

Метод возвращает только модели, доступные тарифу владельца ключа.

Начало работы

Тарифы и стоимость

Оплата состоит из стоимости тарифа и кредитов на балансе. Каждый запрос списывает стоимость фактических входных и выходных токенов по актуальным ценам, указанным в каталоге моделей.

Возможность	Free	Basic	Pro
Цена тарифа	0 ₽	425 ₽ / 30 дней	850 ₽ / 30 дней
Кредиты при активации	1 при регистрации · бессрочно	20 · на срок тарифа	40 · на срок тарифа
Запросов в минуту	10 RPM	25 RPM	50 RPM
Одновременных запросов	До 2	До 2	До 2
Доступ к моделям	Базовые	Free + Basic	Все модели
Креативность	Да	Да	Да
Системный промпт и рассуждения	Нет	Да	Да
Веб-поиск	Да	Да	Да
Вызов функций через API	Нет	Да	Да
Анализ PDF	Да	Да	Да
Чтение TXT	Да	Да	Да
Генерация изображений	Нет	Да	Да
Редактирование изображений	Нет	Нет	Да

PAYG

PAYG (Pay As You Go) — пополнение баланса без ежемесячной подписки по базовой цене 30 ₽ за кредит. Можно выбрать от 3 до 220 кредитов с точностью до сотых; итоговая сумма рассчитывается сервером и округляется вверх до целого рубля перед переходом к оплате. Начисленные кредиты не имеют установленного срока действия. Пополнение не меняет текущий тариф: доступ к моделям и RPM остаются такими, как предусмотрено планом Free, Basic или Pro.

Как рассчитывается запрос

Входные токены включают инструкции и историю диалога. Выходные токены составляют ответ модели. Цена рассчитывается отдельно для обеих частей и отображается в журнале запросов.

Работа с сервисом

Чат и дашборд

Основной чат

Основной чат содержит закреплённый набор моделей. Файлы можно выбрать кнопкой со скрепкой или перетащить в любое место окна чата — ограничения форматов и размеров одинаковы. История диалогов хранится локально в браузере и не переносится автоматически между устройствами. Очистка данных сайта может удалить локальные чаты.

Веб-поиск

Веб-поиск доступен начиная с Free через API POST /v1/responses. Поиск расходует кредиты и учитывается в RPM на общих условиях. В интерфейсе обычного чата веб-поиск недоступен.

Настройки модели

Креативность регулируется от 0.0 до 2.0: низкое значение делает ответы предсказуемее, высокое — разнообразнее. На Basic и Pro можно сохранить собственный системный промпт. Для моделей, которые это поддерживают, также доступны низкая, средняя и высокая степени рассуждения.

Работа с изображениями

У текстовых моделей с компьютерным зрением доступна скрепка: можно приложить до 6 изображений JPG, PNG или WEBP. Перед отправкой изображения оптимизируются до 1600 пикселей по большей стороне и совместимого JPEG до 4 МБ. Модели редактирования требуют текстовую инструкцию и одно изображение. Результат показывается и скачивается с разрешением и соотношением сторон, которые вернула выбранная модель. Генерация доступна с Basic, редактирование — с Pro.

Работа с PDF

В чате можно отправить один PDF размером до 10 МБ вместе с текстовым вопросом. Анализ доступен для текстовых моделей с поддержкой вложений и компьютерного зрения. PDF нельзя объединять с изображениями в одном запросе.

Работа с TXT

В чате можно отправить один непустой файл TXT в кодировке UTF-8 размером до 64 КБ вместе с вопросом. TXT доступен всем текстовым моделям: сервер проверяет файл и передаёт его содержимое модели как текстовый контекст. TXT нельзя смешивать с PDF или изображениями в одном запросе.

Таблицы, графики и схемы

Основной чат отображает Markdown-таблицы, диаграммы Mermaid и графики Chart.js. Попросите модель сравнить данные в таблице, построить график по значениям или показать процесс в виде схемы. Если модель вернёт некорректное описание визуализации, исходный блок останется доступен как код.

Нейро-тест

Нейро-тест позволяет выполнить разовый запрос к дополнительной модели. Дешёвые модели относятся к Free, средние — к Basic, наиболее дорогие — к Pro.

Журнал запросов

Вкладка «Запросы» показывает модель, результат, стоимость, длительность и дату. Она охватывает запросы аккаунта, но не хранит полные тексты пользовательских диалогов.

Реферальная система

За нового пользователя, зарегистрировавшегося по персональной ссылке, владелец ссылки получает 5 кредитов.

API

Авторизация и ключи

Каждый запрос к /v1/* должен содержать API-ключ в заголовке:

Authorization: Bearer xelum_sk_...

Полное значение показывается только сразу после создания. В базе хранится SHA-256-хеш, поэтому посмотреть ключ повторно невозможно. На аккаунте может быть до 10 активных ключей. Все ключи используют общий баланс, тариф, RPM и лимит одновременных запросов аккаунта.

Генерация текста

Метод POST /v1/chat/completions принимает историю сообщений и возвращает одно завершение модели.

{
  "model": "gpt-5-nano",
  "messages": [
    {
      "role": "system",
      "content": "Отвечай кратко."
    },
    {
      "role": "user",
      "content": "Объясни REST API."
    }
  ],
  "max_tokens": 500,
  "temperature": 0.7,
  "reasoning_effort": "medium"
}

Параметры

model: Обязательный ID текстовой модели из каталога.
messages: Массив от 1 до 20 сообщений. Инструкцию задавайте сообщением с role=system.
role: Одна из ролей: system, user, assistant или tool. Для role=tool нужен tool_call_id; assistant может вернуть tool_calls и content=null.
content: Непустая строка до 20 000 символов либо массив из текстовой части и одного файла: PDF до 10 МБ или TXT UTF-8 до 64 КБ; текстовый контекст — до 80 000 символов.
max_tokens: Максимум ответа от 1 до 2048 токенов. Некорректное значение заменяется серверным максимумом.
temperature: Креативность от 0.0 до 2.0, по умолчанию 0.7.
reasoning_effort: Степень рассуждения из effort_types выбранной модели. Конкретный набор может включать none, minimal, low, medium, high, xhigh или max; настройка доступна с Basic.
stream: Для публичного /v1/chat/completions потоковый режим пока не поддерживается. Потоковая выдача используется только внутренним веб-чатом.

PDF через Chat Completions

{
  "model": "gemini-3.1-flash-lite",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "О чём этот документ?"
        },
        {
          "type": "file",
          "file": {
            "filename": "document.pdf",
            "file_data": "data:application/pdf;base64,..."
          }
        }
      ]
    }
  ]
}

PDF через Responses

{
  "model": "gemini-3.1-flash-lite",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Сделай краткое резюме."
        },
        {
          "type": "input_file",
          "file": {
            "filename": "document.pdf",
            "file_data": "data:application/pdf;base64,..."
          }
        }
      ]
    }
  ]
}

TXT через API

Используйте type: "file" в Chat Completions или type: "input_file" в Responses, имя с расширением .txt и file_data вида data:text/plain;base64,.... TXT преобразуется в текстовый контекст и не требует поддержки компьютерного зрения.

{
  "model": "gpt-5-nano",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Сделай краткое резюме."},
        {
          "type": "file",
          "file": {
            "filename": "notes.txt",
            "file_data": "data:text/plain;base64,..."
          }
        }
      ]
    }
  ]
}

Контекст диалога

API не хранит диалог за клиента. Чтобы продолжить разговор, передавайте предыдущие сообщения в следующем запросе. Сервер использует не более последних 20 сообщений.

Руководства

Изображения через API

Генерация создаёт новое изображение по текстовой инструкции. Стоимость указана за один успешно созданный результат и списывается только после успешного ответа поставщика.

Создание изображения

import os
import requests

response = requests.post(
    "https://xelumai.ru/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['XELUM_API_KEY']}"
    },
    json={
        "model": "z-image-turbo",
        "prompt": "Минималистичный ночной город, мягкий свет",
    },
)
response.raise_for_status()
print(response.json()["data"][0]["url"])

const response = await fetch("https://xelumai.ru/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.XELUM_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "z-image-turbo",
    prompt: "Минималистичный ночной город, мягкий свет"
  })
});

if (!response.ok) throw new Error(await response.text());
console.log((await response.json()).data[0].url);

curl https://xelumai.ru/v1/images/generations \
  -H "Authorization: Bearer $XELUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "Минималистичный ночной город, мягкий свет"
  }'

Метод POST /v1/images/generations доступен начиная с Basic. Ответ содержит подписанный адрес XelumAI в data[0].url; клиент открывает и скачивает результат только через домен XelumAI.

Редактирование изображения

curl https://xelumai.ru/v1/images/edits \
  -H "Authorization: Bearer $XELUM_API_KEY" \
  -F "model=gpt-image-1.5-edit" \
  -F "prompt=Замени фон на вечерний город" \
  -F "image=@photo.png"

Метод POST /v1/images/edits доступен на Pro и принимает multipart/form-data. Поддерживаются JPG, PNG и WEBP размером до 10 МБ.

{
  "created": 1793281122,
  "data": [
    {
      "url": "https://..."
    }
  ],
  "xelum": {
    "cost": 0.03
  }
}

Инструменты

Веб-поиск и вызов функций

Function calling доступен через POST /v1/chat/completions на Basic и Pro. Передайте OpenAI-совместимый массив tools с функциями; XelumAI возвращает message.tool_calls, а выполнение, проверка аргументов и повторная отправка результата остаются на стороне вашего приложения. Поддерживается до 32 функций общим описанием до 64 000 символов. Для этого метода используйте stream: false.

{
  "model": "gpt-5-nano",
  "messages": [
    {
      "role": "user",
      "content": "Какая погода?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Получить погоду",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

Необязательный tool_choice передаётся поставщику вместе с tools. После выполнения функции добавьте в следующий запрос ответ с role: "tool" и соответствующим tool_call_id, чтобы модель сформировала итоговый текст.

Веб-поиск доступен начиная с Free через POST /v1/responses с tools: [{"type":"web_search_preview"}]. Метод принимает только инструмент web_search_preview и использует общий баланс, RPM и лимит одновременных запросов аккаунта. Поиск выполняет внешний поставщик; ссылки и факты из результата следует проверять.

curl https://xelumai.ru/v1/responses \
  -H "Authorization: Bearer $XELUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-nano",
    "input": "Новости за сегодня",
    "tools": [
      {
        "type": "web_search_preview"
      }
    ]
  }'

API

Формат ответа

{
  "id": "text-provider-example",
  "object": "chat.completion",
  "model": "gpt-5-nano",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Привет, чем могу помочь?"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 11,
    "completion_tokens": 7,
    "total_tokens": 18
  },
  "xelum": {
    "cost": 0.0006
  }
}

choices[0].message.content: Текст, который нужно показать пользователю.
usage: Количество входных и выходных токенов.
xelum.cost: Списанная стоимость запроса в кредитах.
finish_reason: Причина завершения генерации, полученная от модели.

Справочник

Лимиты и ошибки

{
  "error": {
    "message": "Описание ошибки",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_error"
  }
}

Публичный API `/v1/*`

400: Некорректные параметры запроса. Возможные коды: bad_request, bad_model, bad_prompt, bad_image, bad_pdf, bad_txt, pdf_not_supported, bad_tools, bad_temperature, bad_reasoning_effort, bad_system_prompt и stream_not_supported.
401: authentication_error — API-ключ отсутствует, неверен или был удалён.
402: insufficient_credits — на общем балансе аккаунта недостаточно кредитов.
403: model_locked — модель недоступна тарифу; feature_locked — недоступна настройка; function_calling_locked — для вызова функций требуется Basic или Pro.
413: pdf_too_large, txt_too_large либо превышен размер input или загружаемого изображения.
429: rate_limit_error — превышен RPM; too_many_parallel_requests — уже выполняются два запроса этого аккаунта.
500: internal — внутренняя ошибка обработки изображения.
502: upstream — внешний поставщик или выбранная модель временно не ответили корректно.
504: timeout_error или upstream_timeout — истекло время ожидания модели.

Ошибки чата

Веб-чат дополнительно может вернуть vision_not_supported, request_too_large, too_many_parallel_requests, empty_response или csrf. Эти коды отображаются интерфейсом как понятное сообщение и не означают успешное выполнение запроса.

Коды внутренних API интерфейса

auth означает завершённую или недействительную сессию; bad_request, bad_name и bad_amount — неверные данные; no_credits — недостаточный баланс; image_not_allowed — изображение не подходит выбранной операции; confirmation_required — не введено подтверждение удаления; forbidden — действие доступно только владельцу; not_found — объект не найден; key_limit — уже создано 10 ключей; pending_payment — действие заблокировано незавершённым платежом; payment_rate_limit — слишком много попыток оплаты; payments_unavailable — оплата временно недоступна; interrupted — ответ был остановлен пользователем. Внешним интеграциям следует ориентироваться на OpenAI-совместимый объект error маршрутов /v1/*.

Повтор запросов

При 429, 502 или 504 используйте задержку перед повтором. Не повторяйте запросы без паузы: это увеличивает нагрузку и может снова попасть под RPM.

Обзор XelumAI

Что доступно

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

Модели

Получить доступные модели

Тарифы и стоимость

PAYG

Как рассчитывается запрос

Чат и дашборд

Основной чат

Веб-поиск

Настройки модели

Работа с изображениями

Работа с PDF

Работа с TXT

Таблицы, графики и схемы

Нейро-тест

Журнал запросов

Реферальная система

Авторизация и ключи

Рекомендации

Генерация текста

Параметры

PDF через Chat Completions

PDF через Responses

TXT через API

Контекст диалога

Изображения через API

Создание изображения

Редактирование изображения

Веб-поиск и вызов функций

Формат ответа

Лимиты и ошибки

Публичный API /v1/*

Ошибки чата

Коды внутренних API интерфейса

Повтор запросов

Публичный API `/v1/*`