OpenAI-совместимый API

Как устроен публичный API

Клиент всегда подключается к gateway. Gateway проверяет API-ключ, применяет лимиты аккаунта, считает использование и маршрутизирует запрос на доступную inference-ноду. Конкретный backend-движок модели не является частью публичного контракта.

• GET /v1/models возвращает публичные ID моделей из каталога AI Cloud, а не имена файлов или deployment-имена inference-ноды.
• POST /v1/chat/completions принимает только публичный ID модели из списка; gateway сам переписывает внутренний upstream-запрос.
• Ответ нормализуется под поддерживаемый OpenAI-совместимый формат: choices, usage, finish_reason, tool calls и streaming chunks сохраняются.
• В публичный API не входят внутренние diagnostics inference-движка: пути к model-файлам, quant/deployment-имена, server headers, raw cache/context data и engine-specific timing breakdown.

Точную задержку, time-to-first-token и скорость вывода клиент может измерять на своей стороне по streaming-ответу. Внутренний prefill/decode breakdown используется для операционного мониторинга AI Cloud и не считается частью API.

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

Создайте API-ключ в Панель управления → API-ключи. Ключ показывается один раз при создании — сохраните его в безопасном месте. Передавайте его в заголовке Authorization: Bearer sk_....

GET /v1/models

Возвращает список моделей, доступных в текущей топологии.

curl https://<your-host>/v1/models \
  -H "Authorization: Bearer sk_..."

Используйте точный id из этого ответа в поле model.

POST /v1/chat/completions

Основной endpoint генерации. Поддерживает streaming через stream: true.

curl https://<your-host>/v1/chat/completions \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<точный-id-из-/v1/models>",
    "messages": [
      {"role": "user", "content": "Привет!"}
    ],
    "stream": true
  }'

Поле model должно совпадать с id из GET /v1/models. Незарегистрированные значения вернут 400. Контекст задается выбранной моделью и конфигурацией endpoint, а не тарифом.

Ошибки и лимиты

• 401 — неверный или неактивный API-ключ.
• 402 — недостаточно баланса для платной модели.
• 403 — модель отключена или недоступна.
• 413 — тело запроса слишком большое для gateway или промпт не помещается в контекст выбранной модели.
• 429 — превышен RPM anti-abuse лимит. Снизьте частоту обращений.
• 503 — все GPU-ноды временно загружены, попробуйте позже.

Совместимость с SDK

Пример с официальным OpenAI Python SDK:

from openai import OpenAI

client = OpenAI(
    base_url="https://<your-host>/v1",
    api_key="sk_...",
)

response = client.chat.completions.create(
    model="<точный-id-модели>",
    messages=[{"role": "user", "content": "Hi"}],
)
print(response.choices[0].message.content)