API

Всё, что вы делаете в кабинете, доступно через JSON API.

• Базовый URL: https://api.gysga.com/v1
• Авторизация: Authorization: Bearer gsk_...

API-ключи

Создайте ключ в Настройки → API-ключи. Полный ключ показывается только один раз — сохраните его в менеджере секретов. Можно иметь до 50 ключей и отозвать любой в любой момент. У ключа те же права, что у аккаунта (аренда тратит ваш баланс), поэтому не размещайте его в коде, который выполняется у клиентов (браузер, мобильное приложение).

export GYSGA_API_KEY=gsk_...
curl -s https://api.gysga.com/v1/me -H "Authorization: Bearer $GYSGA_API_KEY"

Деньги и ошибки

• Суммы — целые числа в микродолларах: 1_000_000 = $1. price_hour_micros: 400000 означает $0.40 в час.
• Ошибки возвращаются в JSON с машиночитаемым кодом:

{ "error": "insufficient_funds", "message": "Add funds: the balance must cover at least one hour" }

HTTP	error	Значение
400	invalid, bad_request	Неверные параметры; message объясняет, какие.
401	unauthorized	Ключ отсутствует, неверный или отозван.
402	insufficient_funds	Баланса не хватает на час работы сервера.
404	not_found	Такого сервера нет в вашем аккаунте.
409	no_capacity	Сейчас нет свободных GPU этой модели.
409	gpus_busy	Запуск не удался: GPU машины этого сервера заняты.
409	conflict	Действие недоступно в текущем статусе (например, остановка остановленного сервера).
409	not_running	Прокси: сервер не запущен.
429	rate_limited	Слишком много запросов (около 20 в секунду с одного IP).
502	upstream_unavailable	Прокси: на этом порту ещё никто не отвечает, или хост не в сети.

Методы

Метод	Путь	Описание
GET	/me	Аккаунт и баланс.
GET	/gpus	Модели GPU, цены и наличие.
GET	/catalog	GPU, шаблоны и модели (со статусом кэша).
GET	/instances	Ваши серверы (удалённые — ещё 7 дней).
POST	/instances	Запустить сервер.
GET	/instances/{id}	Один сервер.
PATCH	/instances/{id}	Переименовать: {"label": "..."}.
GET	/instances/{id}/events	Журнал событий, новые сверху.
POST	/instances/{id}/stop	Остановить (данные сохраняются).
POST	/instances/{id}/start	Запустить остановленный сервер.
DELETE	/instances/{id}	Удалить сервер вместе с данными.
любой	/instances/{id}/proxy/{port}/{path}	Прокси к порту внутри сервера.

Действия при успехе возвращают 204 No Content.

GET /me

{
  "user": { "id": 42, "email": "[email protected]", "role": "user", "trust_level": 0,
            "referral_code": "k7m2p9qa", "created_at": "2026-09-27T10:00:00Z" },
  "balance_micros": 25000000
}

GET /gpus

{
  "gpus": [
    { "model": "rtx-4090", "display_name": "NVIDIA RTX 4090", "vram_gb": 24,
      "price_hour_micros": 400000, "tier": "consumer", "arch": "Ada",
      "free_gpus": 6, "max_per_server": 4 }
  ]
}

max_per_server — наибольший gpu_count, который можно заказать прямо сейчас.

GET /catalog

Возвращает gpus (как выше), templates и models. У шаблона есть поля id, category, name, description, image, ports, min_vram_gb, min_cuda, disk_gb, model_kinds, model_required, multi_gpu. У модели — id, hf, name, kind, params, license, min_vram_gb, tier, gated, tags, description, cached, size_gb. См. Шаблоны и Модели.

POST /instances

Поле	Тип	Обязательно	Описание
gpu_model	string	да	например rtx-4090, h100-80gb (см. /gpus).
gpu_count	int	да	1–8, все на одной машине.
template	string	да	id шаблона, например vllm, comfyui, pytorch, custom.
model	string	зависит	id модели; обязателен для vllm, sglang, embeddings, по желанию для comfyui.
image	string	только custom	Публичный Docker-образ, например ghcr.io/me/app:1.2.
disk_gb	int	нет	10–2000; по умолчанию размер из шаблона.
env	object	нет	Переменные окружения, например {"HF_TOKEN": "hf_..."}.
label	string	нет	Ваше название сервера (до 64 символов).

curl -s https://api.gysga.com/v1/instances \
  -H "Authorization: Bearer $GYSGA_API_KEY" -H "Content-Type: application/json" \
  -d '{"gpu_model":"rtx-4090","gpu_count":1,"template":"vllm","model":"qwen3-8b","label":"chat-bot"}'

Ответ 201 Created:

{
  "id": "i-abc12345",
  "label": "chat-bot",
  "status": "creating",
  "status_message": "",
  "desired_state": "running",
  "gpu_model": "rtx-4090",
  "gpu_count": 1,
  "template": "vllm",
  "model": "qwen3-8b",
  "image": "vllm/vllm-openai:v0.30.0-cu129",
  "disk_gb": 60,
  "ports": [ { "port": 8000, "name": "OpenAI API", "kind": "http", "api": "openai", "path": "/v1/models" } ],
  "env": {},
  "token": "k2m4...",
  "price_hour_micros": 400000,
  "machine_id": 17,
  "machine_online": true,
  "created_at": "2026-09-27T10:00:00Z"
}

Опрашивайте GET /instances/{id}, пока status не станет running (тогда заполнится started_at). Статусы описаны в Аренда GPU → Жизненный цикл.

GET /instances/{id}/events

{ "items": [ { "message": "Running", "created_at": "2026-09-27T10:03:12Z" },
             { "message": "Created, waiting for the host to start the container", "created_at": "2026-09-27T10:00:00Z" } ] }

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

https://api.gysga.com/v1/instances/{id}/proxy/{port}/{path}

Любой метод, заголовки и тело (до 512 МБ) передаются на http://localhost:{port}/{path} внутри сервера. Потоковые ответы (Server-Sent Events, chunked) передаются сразу, WebSocket тоже работает.

• Ваш заголовок Authorization (ключ Gysga) и cookie удаляются до того, как запрос попадёт в контейнер.
• Если у сервиса внутри свой ключ, передайте его как X-Upstream-Authorization: Bearer ... — он будет передан как Authorization.

OpenAI SDK и vLLM

Запустите шаблон vllm с моделью и направьте любой OpenAI-клиент на прокси. Имя модели — её id на Hugging Face:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.gysga.com/v1/instances/i-abc12345/proxy/8000/v1",
    api_key="gsk_...",  # ваш API-ключ Gysga
)
resp = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="")

curl https://api.gysga.com/v1/instances/i-abc12345/proxy/8000/v1/chat/completions \
  -H "Authorization: Bearer $GYSGA_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3-8B","messages":[{"role":"user","content":"Hello!"}]}'

Для SGLang используйте порт 30000; для эмбеддингов — /v1/embeddings на порту 8000; OpenAI-совместимый эндпоинт Ollama — на порту 11434.

Полный пример: запуск, ожидание, использование, удаление

import time, requests

API = "https://api.gysga.com/v1"
H = {"Authorization": "Bearer gsk_..."}

inst = requests.post(f"{API}/instances", headers=H, json={
    "gpu_model": "rtx-4090", "gpu_count": 1, "template": "vllm", "model": "qwen3-8b",
}).json()

while True:
    inst = requests.get(f"{API}/instances/{inst['id']}", headers=H).json()
    if inst["status"] == "running":
        break
    if inst["status"] == "error":
        raise RuntimeError(inst["status_message"])
    time.sleep(10)

base = f"{API}/instances/{inst['id']}/proxy/8000"
# После старта контейнера модели может понадобиться минута на загрузку:
while requests.get(f"{base}/v1/models", headers=H).status_code != 200:
    time.sleep(5)

# ... используем ...

requests.delete(f"{API}/instances/{inst['id']}", headers=H)