play2go.ai / docsКонсоль

API и интеграция

Play2Go AI предоставляет REST API. OpenAPI-спецификация публикуется открыто — на её основе можно сгенерировать клиентский SDK на любом языке.

Эндпоинты API

  • Базовый URL: https://api.play2go.ai. Ресурсы по схеме /v1/<resource>.
  • OpenAPI: https://api.play2go.ai/openapi.json + /docs (Swagger UI с интерактивными запросами).

Аутентификация

API-ключ выпускается через «API-ключи». Создание ключа возвращает секрет ровно один раз — сохраните его в менеджере секретов.

bash
# Все запросы — с заголовком Authorization
curl -H "Authorization: Bearer $PLAY2GO_AI_API_KEY" https://api.play2go.ai/v1/pods?projectId=prj_...

Ключ привязан к организации; роль ключа определяет, что он может (см. таблицу ролей в «Аккаунт»). Опционально ключ можно ограничить одним проектом — тогда он не сможет работать с ресурсами других проектов организации.

Скоупы

Скоупы — это узкий слой ограничений поверх роли. Если у ключа есть скоупы — он может только то, что в них перечислено, даже если роль позволяет больше. Без скоупов — действует только роль.

Примеры:

  • pods:read — список и просмотр подов;
  • pods:write — создание/изменение/удаление;
  • endpoints:invoke — отправка задач в эндпоинты;
  • billing:read — чтение биллинга.

Идемпотентность

Все мутирующие методы принимают idempotencyKey — произвольную строку (мы используем UUID). Платформа хранит её и:

  • при первом запросе — выполняет операцию;
  • при повторе с тем же ключом — возвращает предыдущий результат, ничего не делая.

Это позволяет безопасно ретраить запросы при сетевых сбоях. Ключ генерируется на стороне клиента до отправки запроса.

Формат ошибок

Ошибки возвращаются как JSON с кодом и человекочитаемым сообщением:

json
{
  "code": 9,
  "message": "spend limit reached: projected spend exceeds the configured limit",
  "details": []
}

Используйте HTTP-статус для маршрутизации (400 — некорректный запрос, 401 — нет аутентификации, 403 — нет прав, 404 — не найдено, 412 — нарушено предусловие, например достигнут лимит расходов). Поле message можно показывать пользователю как есть.

Примеры curl

Создать под

bash
curl -X POST https://api.play2go.ai/v1/pods \
  -H "Authorization: Bearer $PLAY2GO_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "training-01",
    "projectId": "prj_...",
    "image": "docker.io/library/python:3.12",
    "skuId": "sku_rtx4090",
    "gpuCount": 1,
    "command": ["python"],
    "args": ["-c", "print(\"hi\")"],
    "idempotencyKey": "<uuid>"
  }'

Отправить задачу в эндпоинт

bash
curl -X POST https://api.play2go.ai/v1/endpoints/ep_.../runsync \
  -H "Authorization: Bearer $PLAY2GO_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Hello"}, "waitTimeoutSeconds": 30, "idempotencyKey": "<uuid>"}'

Запросить URL для скачивания файла с тома

bash
curl -X POST https://api.play2go.ai/v1/volumes/vol_.../objects:download-url \
  -H "Authorization: Bearer $PLAY2GO_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objectKey": "results/model.safetensors"}'