Hubris Models API

openapi: 3.2.0
info:
  title: Hubris Models API
  version: 1.0.0
  description: 'OpenAI-совместимый API российского LLM-агрегатора. Все цены в рублях.


    Версии и вывод из эксплуатации (deprecation policy): несовместимые изменения — только в новой версии префикса (`/v2`); об отключении эндпоинта или поля предупреждаем не меньше чем за 90 дней заголовками `Deprecation` (RFC 9745) и `Sunset` (RFC 8594), записью в журнале изменений и письмом. Подробно: https://hubris.pw/docs/api/versioning'
servers:
- url: https://api.hubris.pw
  description: Production
tags:
- name: Models
paths:
  /v1/models:
    get:
      operationId: listModels
      tags:
      - Models
      summary: Список доступных моделей
      description: 'Возвращает активные модели с ценами в рублях за 1М токенов.


        Без параметра — только модели, которые отвечают текстом (в том числе с картинкой или голосом в ответе). Остальные категории — по фильтру `?output_modalities=`: `embeddings`, `image`, `video`, `speech`, `transcription`, `decisions`, `rerank`; весь каталог — `?output_modalities=all`.


        Единицу тарификации даёт `pricing.unit`: `token` — цены за 1М токенов, `unit` — оплата в других единицах (реальная цена в `pricing.per_unit`, токенные поля нулевые), `unknown` — тариф не публикуется, списывается фактическая стоимость. Не умножайте `input_rub_per_million` на токены, не проверив `unit`.


        Ключ необязателен: без него отдаётся публичный каталог, с ключом — тот же каталог плюс ваши цепочки резервных моделей `route/`.


        Бесплатные модели помечены флагом `pricing.is_free`. Не определяйте бесплатность по `input_rub_per_million === 0`: у моделей с оплатой в других единицах (за изображение, за секунду видео) цена за токены нулевая, а запрос платный. У бесплатных есть лимиты на стороне провайдера модели, которые провайдер не публикует, поэтому в пиковые часы возможны ответы 429. Подробности: /docs/concepts/free-models.'
      security:
      - {}
      - bearerAuth: []
      - oauth2:
        - models:read
      parameters:
      - schema:
          type: string
          maxLength: 100
          description: Фильтр по выходной модальности (CSV). Без параметра — `text`; `all` — весь каталог.
          example: decisions
        required: false
        name: output_modalities
        in: query
      responses:
        '200':
          description: OpenAI-совместимый список моделей.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsList'
        '401':
          description: Передан невалидный API-ключ (без ключа каталог отдаётся публично).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsErrorResponse'
        '429':
          description: Превышен дневной лимит ключа.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsErrorResponse'
        '503':
          description: Не удалось получить курс ЦБ РФ — каталог временно недоступен.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsErrorResponse'
components:
  schemas:
    ErrorCode:
      type: string
      enum:
      - invalid_request
      - invalid_api_key
      - insufficient_balance
      - daily_limit_exceeded
      - workspace_limit_exceeded
      - model_not_found
      - exchange_rate_unavailable
      - upstream_error
      - upstream_timeout
      - context_length_exceeded
      - content_policy_violation
      - input_image_rejected
      - not_found
      - internal_error
      - too_many_active_jobs
      - video_not_ready
      - index_out_of_range
      - byok_disabled
      - byok_egress_unavailable
      - byok_not_configured
      - byok_insufficient_credits
      - byok_not_supported_for_videos
    ErrorObject:
      type: object
      properties:
        message:
          type: string
        type:
          type: string
        code:
          $ref: '#/components/schemas/ErrorCode'
        param:
          type: string
          nullable: true
      required:
      - message
      - type
      - code
    ModelsList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
      required:
      - object
      - data
    Model:
      type: object
      properties:
        id:
          type: string
          example: anthropic/claude-haiku-4.5
        object:
          type: string
          enum:
          - model
        created:
          type: integer
          description: Unix-timestamp последнего обновления записи в каталоге Hubris.
        owned_by:
          type: string
          example: anthropic
        display_name:
          type: string
          example: Claude Haiku 4.5
        description:
          type: string
          nullable: true
          description: Описание модели на русском языке (если переведено).
        context_window:
          type: integer
          example: 200000
        context_length:
          type: integer
          description: То же, что `context_window`, — под именем, которое читают многие OpenAI-совместимые клиенты (RAGFlow и другие).
          example: 200000
        modalities:
          type: array
          items:
            type: string
          description: Legacy OpenAI поле — равно `output_modalities`. Используйте `output_modalities` / `input_modalities` для точного фильтра.
          example:
          - text
          - image
        input_modalities:
          type: array
          items:
            type: string
          description: 'Что модель принимает на вход: `text`, `image`, `audio`, `file`.'
          example:
          - text
          - image
        output_modalities:
          type: array
          items:
            type: string
          description: 'Что модель возвращает: `text` (chat / responses), `embeddings` (только /v1/embeddings), `image`, `audio`.'
          example:
          - text
        supported_parameters:
          type: array
          items:
            type: string
          description: 'Параметры запроса, которые поддерживает модель: `tools`, `tool_choice`, `reasoning`, `include_reasoning`, `response_format`, `structured_outputs`, `temperature`, `top_p`, `seed`, `stop`, `web_search_options` и другие. Клиент по этому списку решает, показывать ли настройки инструментов и размышления для конкретной модели, а не включает их вслепую. Пустой массив — список для модели неизвестен.'
          example:
          - tools
          - tool_choice
          - reasoning
          - temperature
          - max_tokens
          - response_format
          - structured_outputs
        supported_voices:
          type: array
          items:
            type: string
          description: 'Голоса модели озвучки (только у моделей с `output_modalities: ["speech"]`). Значение для поля `voice` в POST /v1/audio/speech.'
          example:
          - en-US-Harper:MAI-Voice-2
        pricing:
          type: object
          properties:
            unit:
              type: string
              enum:
              - token
              - unit
              - unknown
              description: 'Единица тарификации. `token` — цены в `input_rub_per_million` / `output_rub_per_million` за 1М токенов. `unit` — тарификация в других единицах (изображение, мегапиксель, минута, секунда видео), реальная цена в `per_unit`, а токенные поля равны нулю. `unknown` — провайдер не публикует тариф, списывается фактическая стоимость запроса. Считайте бюджет по этому полю: у нетокенных моделей нельзя умножать `input_rub_per_million` на число токенов.'
              example: token
            input_rub_per_million:
              type: number
              description: 'Цена за 1М входных токенов. Осмысленна только при `unit: "token"`; иначе 0 — смотрите `per_unit`.'
              example: 30.45
            output_rub_per_million:
              type: number
              description: 'Цена за 1М выходных токенов. Осмысленна только при `unit: "token"`; иначе 0 — смотрите `per_unit`.'
              example: 152.25
            currency:
              type: string
              enum:
              - RUB
            per_unit:
              type: array
              items:
                type: object
                properties:
                  sku:
                    type: string
                    example: Output Image
                  price_rub:
                    type: number
                    example: 3.6
                  unit:
                    type: string
                    example: per megapixel
                required:
                - sku
                - price_rub
                - unit
              description: Цены за единицу (изображение, мегапиксель, reference). Присутствует только для моделей с unit-pricing — Flux, Recraft, Sourceful, Gemini Image.
            is_free:
              type: boolean
              description: 'Бесплатна ли модель. Определяет сервер: нулевые цены во ВСЕХ единицах тарификации и немедийный выход. Ориентируйтесь на этот флаг, а не на `input_rub_per_million === 0`: у моделей с оплатой за изображение или секунду видео цена за токены нулевая, но запрос платный.'
              example: false
          required:
          - unit
          - input_rub_per_million
          - output_rub_per_million
          - currency
          - is_free
      required:
      - id
      - object
      - created
      - owned_by
      - display_name
      - description
      - context_window
      - context_length
      - modalities
      - input_modalities
      - output_modalities
      - supported_parameters
      - pricing
    ModelsErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
      - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk-gw-...
      description: API-ключ в формате `sk-gw-` + 32 hex. Создаётся в дашборде на /keys. Обычный ключ даёт все права, ключ только для чтения не может тратить баланс.
    oauth2:
      type: oauth2
      description: 'OAuth-токен приложения с ограниченными правами. Регистрация клиента — `POST /oauth/clients` (RFC 7591), PKCE S256 обязателен. Метаданные: `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`.'
      flows:
        authorizationCode:
          authorizationUrl: https://api.hubris.pw/oauth/authorize
          tokenUrl: https://api.hubris.pw/oauth/token
          refreshUrl: https://api.hubris.pw/oauth/token
          scopes:
            chat:write: 'Запросы к моделям от имени пользователя (списывают баланс): чат, Responses, Messages, эмбеддинги, реранкеры, модели решений, изображения, распознавание и озвучка речи, расшифровка видео; коннекторы Битрикс24.'
            models:read: Видеть цепочки резервных моделей пользователя в `GET /v1/models`.
            balance:read: Видеть остаток баланса пользователя.
            videos:write: Создавать видео от имени пользователя (`POST /v1/videos`, резервирует и списывает баланс).
            videos:read: Узнавать статус и скачивать видео пользователя (`GET /v1/videos/{id}`, `GET /v1/videos/{id}/content`).
            offline_access: Выдать refresh-токен, чтобы подключение жило 90 дней без повторного входа.