REST API: GPU и SSH-ключи

REST API: GPU и SSH-ключи

Помимо OpenAI-совместимого инференса (/chat/completions, /models) и Anthropic Messages на origin приложения (/v1/messages — см. Claude Code), тот же базовый адрес /api/v1 и тот же API-ключ cc-… позволяют управлять GPU-серверами и SSH-ключами из скриптов и CI.

Требования

  • Положительный баланс команды (как для инференса)
  • API-ключ, созданный в разделе API-доступ — ключи, созданные только в старом разделе «API-модели», тоже работают; для SSH через API рекомендуется создать ключ заново в API-доступ (привязка к пользователю)

Базовый адрес

https://app.cloudcompute.ru/api/v1

Авторизация: Authorization: Bearer cc-…

Эндпоинты (MVP)

Метод Путь Описание
GET /offers Каталог GPU-предложений (фильтры: gpu_name, num_gpus, min_vram, max_price_rub, sort, limit, offset)
GET /instances Список инстансов команды
POST /instances Создать инстанс (ask_id, template_image, disk_gb, ssh_key_ids, …)
GET /instances/{id} Детали инстанса
PATCH /instances/{id} Обновить метку (label, name)
DELETE /instances/{id} Удалить инстанс
POST /instances/{id}/terminal-token Выдать WebSocket URL для веб-терминала (автоматизация)
GET /ssh-keys SSH-ключи владельца ключа
POST /ssh-keys Добавить ключ (name, public_key)
DELETE /ssh-keys/{id} Удалить ключ

Полное описание полей и примеры ответов — в справочнике API (генерируется автоматически).

Пример: список инстансов

curl https://app.cloudcompute.ru/api/v1/instances \
  -H "Authorization: Bearer cc-..."

Пример: создать инстанс

Минимальный набор полей совпадает с формой в панели: type, ask_id, образ (template_image или template_hash_id), при необходимости disk_gb и ssh_key_ids.

curl -X POST https://app.cloudcompute.ru/api/v1/instances \
  -H "Authorization: Bearer cc-..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": 0,
    "ask_id": 12345678,
    "name": "training-1",
    "template_image": "nvidia/cuda:12.1-devel-ubuntu22.04",
    "offer_disk_space": 50,
    "disk_gb": 32
  }'

Цена (price_hour) пересчитывается на сервере — не передавайте её из клиента.

Поля инстанса в ответе

GET /instances и GET /instances/{id} возвращают объект инстанса, в том числе:

Поле Описание
web_terminal_host Хост для веб-терминала (если доступен)
web_terminal_port Порт ttyd
web_terminal_url Прямой URL терминала (может быть null, если доступ только через прокси)
web_terminal_ready true, когда терминал готов к подключению
ports Карта именованных портов (SSH, Jupyter и др.) или null

Веб-терминал через API

Для автоматизации (CI, скрипты) можно получить временный WebSocket URL с ограниченным сроком действия:

curl -X POST https://app.cloudcompute.ru/api/v1/instances/12345/terminal-token \
  -H "Authorization: Bearer cc-..."

Ответ:

{ "ws_url": "wss://…", "expires_in": 300 }

Подключайтесь к ws_url клиентом ttyd/WebSocket. URL действует ограниченное время (expires_in в секундах).

Bootstrap-профиль и onstart при создании

В теле POST /instances можно задать, какой стартовый скрипт установит доступ к инстансу:

Поле Описание
bootstrap_profile Предпочтительный способ: full, access_only, worker, none
install_monitoring Устаревший boolean; если bootstrap_profile не передан, false → access_only, true → full
onstart Дополнительный shell-фрагмент к bootstrap (full, access_only, worker); при none ваш onstart — единственный стартовый скрипт

Семантика профилей:

Профиль Что устанавливается
full SSH, веб-терминал (ttyd), Jupyter, агент мониторинга
access_only SSH, ttyd, Jupyter — без агента мониторинга
worker Минимальная оболочка SSH/ttyd, затем команда образа (CMD)
none Без bootstrap-скрипта CloudCompute; можно передать свой onstart

Итоговый onstart-скрипт (bootstrap + ваш onstart) не должен превышать 16 384 байта — иначе запрос вернёт ошибку валидации.

Пример: worker + свой onstart

curl -X POST https://app.cloudcompute.ru/api/v1/instances \
  -H "Authorization: Bearer cc-..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": 0,
    "ask_id": 12345678,
    "name": "worker-1",
    "template_image": "nvidia/cuda:12.1-devel-ubuntu22.04",
    "offer_disk_space": 50,
    "disk_gb": 32,
    "bootstrap_profile": "worker",
    "onstart": "cd /workspace && python train.py"
  }'

Ошибки

REST-эндпоинты возвращают JSON вида:

{ "error": { "message": "…", "code": "insufficient_balance" } }

Инференс (/chat/completions) по-прежнему использует OpenAI-совместимый формат ошибок.

См. также

← Предыдущая Оплата и лимиты Следующая → Claude Code