API Nurax
Программный доступ к платформе Nurax — управление облачными компьютерами, публикация, интеграции, биллинг, полные примеры кода.
API Nurax
Платформа Nurax предоставляет программный интерфейс (API) для управления облачными компьютерами, пользователями и биллингом. API позволяет автоматизировать рабочие процессы и интегрировать Nurax в вашу инфраструктуру.
Общая информация
- Базовый URL:
https://next.nurax.ai/v1 - Формат данных: JSON
- Авторизация: Bearer-токен (access token Supabase)
- Все запросы должны содержать заголовок
Content-Type: application/json - Ошибки возвращаются в формате
{"error": {"message": "...", "code": "..."}}
Аутентификация
Для работы с API необходимо получить access-токен. Это можно сделать через стандартный парольный грант Supabase:
curl -X POST https://vaqebxbxprmbmfpimisg.supabase.co/auth/v1/token?grant_type=password \
-H "apikey: ВАШ_ANON_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "ВАШ_EMAIL", "password": "ВАШ_ПАРОЛЬ"}'Ответ будет содержать access_token, который нужно передавать в заголовке:
curl https://next.nurax.ai/v1/platform/sandbox \
-H "Authorization: Bearer ВАШ_ACCESS_TOKEN"Основные эндпоинты
Облачные компьютеры
| Метод | Эндпоинт | Описание |
|---|---|---|
POST | /v1/platform/sandbox | Создать новый облачный компьютер |
GET | /v1/platform/sandbox | Список всех облачных компьютеров пользователя |
GET | /v1/platform/sandbox/:id | Получить информацию об облачном компьютере |
GET | /v1/platform/sandbox/:id/status | Получить статус и стадию провиженинга |
POST | /v1/platform/sandbox/:id/stop | Остановить облачный компьютер |
POST | /v1/platform/sandbox/:id/start | Запустить облачный компьютер |
POST | /v1/platform/sandbox/:id/restart | Перезапустить облачный компьютер |
DELETE | /v1/platform/sandbox/:id | Удалить облачный компьютер |
POST | /v1/platform/sandbox/:id/update | Обновить версию облачного компьютера |
Пример: создание облачные компьютеры
curl -X POST https://next.nurax.ai/v1/platform/sandbox \
-H "Authorization: Bearer ВАШ_ТОКЕН" \
-H "Content-Type: application/json" \
-d '{"provider": "opensandbox"}'
# Ответ:
{
"data": {
"sandbox_id": "sb_abc123",
"status": "provisioning",
"stage": "creating"
}
}Пример: получение статуса
curl https://next.nurax.ai/v1/platform/sandbox/sb_abc123/status \
-H "Authorization: Bearer ВАШ_ТОКЕН"
# Ответ (provisioning):
{
"status": "provisioning",
"stage": "loading_image",
"stageProgress": 42,
"stageMessage": "Загружаем образ..."
}
# Ответ (готово):
{
"status": "active",
"stage": "ready",
"stageProgress": 100,
"stageMessage": "Готово!",
"version": "0.9.9"
}Модели
| Метод | Эндпоинт | Описание |
|---|---|---|
GET | /v1/models | Список всех доступных моделей с ценами |
GET | /v1/platform/sandbox/version/latest | Информация о последней версии облачного компьютера |
Биллинг
| Метод | Эндпоинт | Описание |
|---|---|---|
POST | /v1/billing/setup/initialize | Инициализация биллинга для нового пользователя |
POST | /v1/billing/checkout | Создать сессию оплаты |
GET | /v1/billing/subscription | Информация о подписке |
GET | /v1/billing/credits | Баланс AI-кредитов |
Публикация
| Метод | Эндпоинт | Описание |
|---|---|---|
POST | /v1/platform/sandbox/:id/preview/start | Опубликовать порт облачного компьютера |
POST | /v1/platform/sandbox/:id/preview/stop | Остановить публикацию порта |
GET | /v1/p/:id/:port | Публичный доступ к приложению в облачном компьютере |
GET | /v1/p/share/:token | Доступ к опубликованному приложению по токену |
Управление облачным компьютером
| Метод | Эндпоинт | Описание |
|---|---|---|
POST | /v1/platform/sandbox/:id/stop | Остановить облачный компьютер |
POST | /v1/platform/sandbox/:id/start | Запустить облачный компьютер |
POST | /v1/platform/sandbox/:id/restart | Перезапустить облачный компьютер |
DELETE | /v1/platform/sandbox/:id | Удалить облачный компьютер |
Полный цикл: создание и ожидание облачные компьютеры
Вот пример скрипта на Node.js, который логинится, создаёт облачный компьютер и ждёт её готовности:
const SUPABASE_URL = 'https://vaqebxbxprmbmfpimisg.supabase.co';
const SUPABASE_ANON_KEY = 'ВАШ_ANON_KEY';
const API = 'https://next.nurax.ai/v1';
const EMAIL = 'ВАШ_EMAIL';
const PASSWORD = 'ВАШ_ПАРОЛЬ';
async function login() {
const res = await fetch(`${SUPABASE_URL}/auth/v1/token?grant_type=password`, {
method: 'POST',
headers: {
apikey: SUPABASE_ANON_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ email: EMAIL, password: PASSWORD }),
});
const { access_token } = await res.json();
return access_token;
}
async function createAndWait(token) {
// Создание облачного компьютера
const res = await fetch(`${API}/platform/sandbox`, {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ provider: 'opensandbox' }),
});
const { data } = await res.json();
const sandboxId = data.sandbox_id;
console.log('Облачный компьютер создаётся:', sandboxId);
// Ожидание готовности (опрос каждые 3 секунды)
for (;;) {
const statusRes = await fetch(`${API}/platform/sandbox/${sandboxId}/status`, {
headers: { Authorization: `Bearer ${token}` },
});
const status = await statusRes.json();
console.log(
`[${status.stageProgress || 0}%] ${status.stageMessage || status.stage || ''}`
);
if (status.status === 'active') {
console.log('Облачный компьютер готов!');
return sandboxId;
}
if (status.status === 'error') {
throw new Error('Ошибка: ' + (status.error || 'неизвестная ошибка'));
}
await new Promise(r => setTimeout(r, 3000));
}
}
// Запуск
const token = await login();
const id = await createAndWait(token);
console.log('ID облачного компьютера:', id);Полный цикл: публикация приложения
# 1. Получить токен
TOKEN=$(curl -s -X POST "..." | jq -r '.access_token')
# 2. Создать облачный компьютер
SANDBOX=$(curl -s -X POST "https://next.nurax.ai/v1/platform/sandbox" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"provider": "opensandbox"}' | jq -r '.data.sandbox_id')
echo "Песочница: $SANDBOX"
# 3. Опубликовать порт (после запуска приложения на порту 8080)
curl -X POST "https://next.nurax.ai/v1/platform/sandbox/$SANDBOX/preview/start" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"port": 8080}'Обработка ошибок API
API возвращает ошибки в стандартном формате:
{
"error": {
"message": "Описание ошибки",
"code": "error_code"
}
}| HTTP-статус | Значение | Что делать |
|---|---|---|
400 | Неверный запрос | Проверьте параметры запроса |
401 | Не авторизован | Обновите токен |
403 | Нет доступа | Проверьте права |
404 | Не найдено | Проверьте ID облачные компьютеры |
429 | Слишком много запросов | Подождите перед повтором |
500 | Внутренняя ошибка | Попробуйте позже, обратитесь в поддержку |
Rate Limiting
API имеет ограничение на количество запросов:
- Создание облачных компьютеров: не более 5 в час
- Статус облачные компьютеры: не более 60 запросов в минуту
- Остальные эндпоинты: не более 30 запросов в минуту
При превышении лимита API возвращает 429 Too Many Requests. Заголовки ответа содержат информацию о лимитах: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Python-клиент
Пример на Python для автоматизации:
import time
import requests
API = "https://next.nurax.ai/v1"
class NuraxClient:
def __init__(self, token: str):
self.headers = {"Authorization": f"Bearer {token}"}
def create_sandbox(self) -> str:
res = requests.post(
f"{API}/platform/sandbox",
headers=self.headers,
json={"provider": "opensandbox"}
)
return res.json()["data"]["sandbox_id"]
def wait_until_ready(self, sandbox_id: str, timeout: int = 120):
start = time.time()
while time.time() - start < timeout:
res = requests.get(
f"{API}/platform/sandbox/{sandbox_id}/status",
headers=self.headers
)
status = res.json()
print(f"[{status.get('stageProgress', 0)}%] {status.get('stageMessage', '')}")
if status["status"] == "active":
return True
if status["status"] == "error":
raise Exception(status.get("error", "Unknown error"))
time.sleep(3)
raise TimeoutError("Песочница не создался за отведённое время")
def get_credits(self) -> dict:
res = requests.get(f"{API}/billing/credits", headers=self.headers)
return res.json()
def stop_sandbox(self, sandbox_id: str):
requests.post(f"{API}/platform/sandbox/{sandbox_id}/stop", headers=self.headers)
# Использование
client = NuraxClient("ВАШ_ТОКЕН")
sandbox_id = client.create_sandbox()
client.wait_until_ready(sandbox_id)
print(f"Песочница {sandbox_id} готова!")Подсказки
- Токены имеют ограниченное время жизни. При получении
401— получите новый токен - ID облачных компьютеров начинаются с префикса
sb_ - Статус provisioning означает, что облачный компьютер ещё создаётся
- Публикация порта будет активна, пока приложение слушает порт
- Все эндпоинты, кроме
/auth/v1/token, требуют Bearer-авторизации
Подробнее об облачных компьютерах — в разделе Песочницы.