Hubris Audio API

openapi: 3.2.0
info:
  title: Hubris Audio 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: Audio
paths:
  /v1/audio/transcriptions:
    post:
      operationId: createTranscription
      tags:
      - Audio
      summary: Распознать речь в аудио
      description: 'OpenAI-совместимое распознавание речи: аудиозапись на входе, текст на выходе. Работает официальный SDK OpenAI (`audio.transcriptions.create`).


        Два формата тела с одинаковым результатом: `multipart/form-data` с файлом, как у OpenAI, или `application/json` с аудио в base64 (`input_audio`). Ссылки на аудио не принимаются.


        Стрима нет: `stream: true` — 400. `response_format` — только `json` или `verbose_json`.


        Оплата по факту запроса: `usage.cost` — списано в копейках. Часть моделей тарифицируется по длительности записи, часть по токенам. Список моделей: `GET /v1/models?output_modalities=transcription`.'
      security:
      - bearerAuth: []
      - oauth2:
        - chat:write
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TranscriptionMultipartRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/TranscriptionJsonRequest'
      responses:
        '200':
          description: Распознанный текст.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscriptionResponse'
        '400':
          description: 'Невалидное тело: нет `model`, `file` или `input_audio`, `stream: true`, неподдерживаемый `response_format`; ключ BYOK.'
        '401':
          description: Ключ не передан, невалиден, отозван или заморожен (`invalid_api_key`, `key_frozen_spike`).
        '402':
          description: Недостаточно средств на балансе (`insufficient_balance`).
        '403':
          description: 'Нет права `chat:write`: ключ только для чтения (`key_read_only`) или OAuth-токен без него (`insufficient_scope`). Ещё причины: management-ключ (`inference_key_required`), запрос не с адреса, к которому привязан ключ (`key_ip_not_allowed`), или заблокированный аккаунт (`account_blocked`).'
        '404':
          description: Модель не найдена или это не модель распознавания (`model_not_found`).
        '413':
          description: Тело запроса больше лимита (`request_too_large`).
        '429':
          description: Исчерпан лимит расхода ключа (`daily_limit_exceeded`, `key_limit_exceeded`), лимит пространства (`workspace_limit_exceeded`) или провайдер временно ограничил запросы. Пауза — в `Retry-After`.
        '502':
          description: Ошибка провайдера или не удалось определить стоимость (`pricing_unavailable`). Списания нет.
        '503':
          description: Курс ЦБ РФ временно недоступен (`exchange_rate_unavailable`).
        '504':
          description: Таймаут распознавания (`upstream_timeout`).
  /v1/audio/speech:
    post:
      operationId: createSpeech
      tags:
      - Audio
      summary: Озвучить текст
      description: 'OpenAI-совместимая озвучка (TTS): текст на входе, байты аудио на выходе, а не JSON. Работает официальный SDK OpenAI (`audio.speech.create`).


        Формат — `response_format`: `mp3` (`audio/mpeg`) или `pcm` (`audio/pcm` с частотой и числом каналов в `Content-Type`, 16-bit LE без заголовка WAV). Без поля формат выбирает модель. Стрима нет.


        `voice` обязателен, если у модели в каталоге есть список голосов; голос не из списка отклоняется до обращения к модели.


        Цена — по единице модели в каталоге: символы или байты текста, секунды звука, токены. Списание по факту запроса; `usage` в ответе нет, расход — в журнале запросов. Перед запросом баланс сверяется с оценкой цены. Список моделей: `GET /v1/models?output_modalities=speech`.'
      security:
      - bearerAuth: []
      - oauth2:
        - chat:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeechRequest'
      responses:
        '200':
          description: Аудио целиком.
          headers:
            Content-Length:
              description: Размер аудио в байтах.
              schema:
                type: integer
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
            audio/pcm:
              schema:
                type: string
                format: binary
        '400':
          description: Невалидное тело (`invalid_request`), не выбран голос (`voice_required`), голоса нет у модели (`voice_not_supported`); ключ BYOK. В тексте ошибки — доступные голоса.
        '401':
          description: Ключ не передан, невалиден, отозван или заморожен (`invalid_api_key`, `key_frozen_spike`).
        '402':
          description: Баланса не хватает на оценку цены запроса (`insufficient_balance`).
        '403':
          description: 'Нет права `chat:write`: ключ только для чтения (`key_read_only`) или OAuth-токен без него (`insufficient_scope`). Ещё причины: management-ключ (`inference_key_required`), запрос не с адреса, к которому привязан ключ (`key_ip_not_allowed`), или заблокированный аккаунт (`account_blocked`).'
        '404':
          description: Модель не найдена или это не модель озвучки (`model_not_found`).
        '413':
          description: Тело запроса больше 1 МБ (`request_too_large`).
        '429':
          description: Исчерпан лимит расхода ключа (`daily_limit_exceeded`, `key_limit_exceeded`), лимит пространства (`workspace_limit_exceeded`) или провайдер временно ограничил запросы. Пауза — в `Retry-After`.
        '502':
          description: Нечем посчитать цену (`pricing_unavailable`), модель вернула пустой ответ (`no_audio_returned`), не удалось перекодировать в mp3 (`transcode_failed`) или ошибка провайдера. Списания нет.
        '503':
          description: Курс ЦБ РФ временно недоступен (`exchange_rate_unavailable`).
        '504':
          description: Таймаут озвучки (`upstream_timeout`).
components:
  schemas:
    TranscriptionMultipartRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: 'Аудиофайл: WAV, MP3, FLAC, M4A, OGG, WebM, AAC. До 25 МБ.'
        model:
          type: string
          minLength: 1
          example: openai/whisper-1
        language:
          type: string
          description: Язык записи в ISO-639-1 (`ru`, `en`). Без поля язык определяется сам.
        prompt:
          type: string
          description: 'Подсказка: имена, термины, аббревиатуры, которые встречаются в записи.'
        temperature:
          type: number
        response_format:
          type: string
          enum:
          - json
          - verbose_json
          description: '`text`, `srt` и `vtt` не поддерживаются (400). Поддержка `verbose_json` зависит от модели.'
        timestamp_granularities[]:
          type: array
          items:
            type: string
            enum:
            - segment
            - word
          description: Таймкоды в `verbose_json`; поддерживаются не всеми моделями.
      required:
      - file
      - model
    TranscriptionResponse:
      type: object
      properties:
        text:
          type: string
          description: 'Распознанный текст. Пустая строка — тоже результат: в записи тишина.'
        usage:
          type: object
          properties:
            seconds:
              type: number
              description: Длительность обработанного аудио в секундах, если модель её сообщает.
            input_tokens:
              type: integer
            output_tokens:
              type: integer
            total_tokens:
              type: integer
            cost:
              type: integer
              description: Списано с баланса, в копейках.
      required:
      - text
    TranscriptionJsonRequest:
      type: object
      properties:
        model:
          type: string
          minLength: 1
          example: openai/whisper-1
        input_audio:
          type: object
          properties:
            data:
              type: string
              minLength: 1
              description: Аудио в base64 (без data:-префикса).
            format:
              type: string
              minLength: 1
              description: 'Формат: wav, mp3, flac, m4a, ogg, webm, aac.'
              example: mp3
          required:
          - data
          - format
          description: Аудио для распознавания. Прямые URL не поддерживаются.
      required:
      - model
      - input_audio
    SpeechRequest:
      type: object
      properties:
        model:
          type: string
          minLength: 1
          example: microsoft/mai-voice-2-flash
        input:
          type: string
          minLength: 1
          maxLength: 50000
          description: 'Текст для озвучки. Цена — по единице модели в каталоге: за символы текста или за токены (у Gemini 25 токенов на секунду звука).'
          example: Привет! Это проверка озвучки.
        voice:
          type: string
          minLength: 1
          description: Голос модели. Список — в карточке модели каталога (поле «Голоса»); обязателен, если список есть.
          example: en-US-Harper:MAI-Voice-2
        response_format:
          type: string
          enum:
          - mp3
          - pcm
          description: 'Формат аудио: mp3 или pcm (16-bit LE). Без поля формат выбирает модель, как правило pcm.'
      required:
      - model
      - input
  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 дней без повторного входа.