Обзор API

Hubris API совместим с OpenAI Chat Completions API. Все запросы — поверх HTTPS, авторизация через Bearer-токен, ответы — JSON с UTF-8.

Базовый URL

https://api.hubris.pw/v1

Все эндпоинты идут от этого префикса. Например, https://api.hubris.pw/v1/chat/completions или https://api.hubris.pw/v1/models.

Заголовки

Обязательные:

• Authorization: Bearer sk-gw-<32-hex> — ваш API-ключ. См. Аутентификацию.
• Content-Type: application/json — для всех POST-запросов.

Опциональные:

• Accept: application/json — явно ожидать JSON-ответ. По умолчанию мы и так отдаём JSON.
• Accept: text/event-stream — при stream: true сервер автоматически переключается в SSE-режим.

Эндпоинты

Версионирование

Префикс /v1 — стабильный. Все breaking-change эндпоинтов будут идти под /v2/... (или новее), не ломая существующие интеграции.

/v1/responses помечен BETA — структура входа/выхода может измениться без major-bump-а. Использовать в продакшене не рекомендуем до перехода в стабильный статус.

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

POST /v1/chat/completions и POST /v1/responses не идемпотентны — каждый запрос порождает новое generation, независимо от тела. Если у вас retry-логика, помните: каждая повторная попытка спишет деньги, если первая прошла успешно (что бывает в редких сетевых сбоях).

GET /v1/models идемпотентен — ответ кешируется на стороне Hubris ~60 секунд.

Стриминг

При stream: true ответ приходит через Server-Sent Events. Подробности формата — на отдельной странице Streaming.

Ошибки

Все ошибки в OpenAI-формате { error: { message, type, code } }. Полный список кодов — на странице Ошибки.

Что дальше

• POST /v1/chat/completions — основной эндпоинт.
• GET /v1/models — каталог.
• Streaming — формат SSE.
• POST /v1/responses — beta-эндпоинт OpenAI Responses API.