Hubris Videos API

openapi: 3.2.0
info:
  title: Hubris Videos 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: Videos
paths:
  /v1/videos:
    post:
      operationId: createVideo
      tags:
      - Videos
      summary: Создать задачу генерации видео
      description: 'Асинхронная генерация: ответ 202 сразу приносит номер задачи и `polling_url`. Статус — `GET /v1/videos/{id}`, готовый ролик — `GET /v1/videos/{id}/content`.


        Перед запуском с баланса удерживается не меньше наибольшей возможной стоимости ролика. После готовности списывается факт (`usage.cost`), разница возвращается; при сбое удержание возвращается целиком. Готовый ролик хранится 72 часа.


        Нужен обычный ключ: ключ только для чтения задачу не создаст. Модели, их оси и цены — `GET /v1/videos/models`.'
      security:
      - bearerAuth: []
      - oauth2:
        - videos:write
      parameters:
      - schema:
          type: string
          maxLength: 255
          description: Повтор с тем же ключом от того же аккаунта вернёт уже созданную задачу без нового удержания. Ключ длиннее 255 знаков не учитывается.
        required: false
        name: Idempotency-Key
        in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVideoRequest'
      responses:
        '202':
          description: Задача создана (или найдена по `Idempotency-Key`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoJobCreated'
        '400':
          description: 'Невалидное тело (`invalid_request`): ось, которой нет у модели, `callback_url`, неподходящие `input_references` или `provider.options`; ключ BYOK. Отказ модели принять вход приходит с её текстом.'
        '401':
          description: Ключ не передан, невалиден, отозван или заморожен (`invalid_api_key`, `key_frozen_spike`).
        '402':
          description: Не хватает средств на удержание под задачу (`insufficient_balance`).
        '403':
          description: 'Нет права создавать задачи: ключ только для чтения (`key_read_only`). OAuth-токен без права `videos:write` (`insufficient_scope`). Ещё причины: management-ключ (`inference_key_required`), запрос не с адреса, к которому привязан ключ (`key_ip_not_allowed`), или заблокированный аккаунт (`account_blocked`).'
        '404':
          description: Модель не найдена или это не видеомодель (`model_not_found`).
        '413':
          description: Тело запроса больше лимита (`request_too_large`).
        '429':
          description: Достигнут лимит одновременных видеозадач аккаунта или уже готовится другой исходник (`too_many_active_jobs`); удержание не помещается в остаток лимита расхода ключа или OAuth-приложения (`daily_limit_exceeded`, `key_limit_exceeded`) или лимита пространства (`workspace_limit_exceeded`).
        '500':
          description: Внутренняя ошибка (`internal_error`).
        '502':
          description: Провайдер не принял задачу (`upstream_error`). Удержание возвращается.
        '503':
          description: Курс ЦБ РФ временно недоступен — не посчитать удержание (`exchange_rate_unavailable`).
        '504':
          description: Провайдер не ответил вовремя (`upstream_error`). Удержание возвращается.
  /v1/videos/{id}:
    get:
      operationId: getVideo
      tags:
      - Videos
      summary: Статус задачи генерации видео
      description: 'Статус: `pending`, `in_progress`, `completed` или `failed`. При `completed` — `unsigned_urls` (адрес скачивания, нужен тот же ключ или токен) и `usage.cost`, итоговое списание в копейках; пока задача в работе — `usage.estimated_cost`, удержанная сумма.


        Статус у провайдера запрашивается не чаще раза в 5 секунд на задачу, опрашивать чаще смысла нет. Подходит и ключ только для чтения.'
      security:
      - bearerAuth: []
      - oauth2:
        - videos:read
      parameters:
      - schema:
          type: string
          format: uuid
          description: Номер задачи из ответа `POST /v1/videos`.
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Задача.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoJob'
        '401':
          description: Ключ не передан, невалиден, отозван или заморожен (`invalid_api_key`, `key_frozen_spike`).
        '403':
          description: 'OAuth-токен без права `videos:read` (`insufficient_scope`). Ещё причины: management-ключ (`inference_key_required`), запрос не с адреса, к которому привязан ключ (`key_ip_not_allowed`), или заблокированный аккаунт (`account_blocked`).'
        '404':
          description: Задачи нет или она принадлежит другому аккаунту (`not_found`).
  /v1/videos/{id}/content:
    get:
      operationId: getVideoContent
      tags:
      - Videos
      summary: Скачать готовое видео
      description: 'Байты готового ролика для задачи в статусе `completed` — только владельцу, тем же ключом или OAuth-токеном. Тип — сохранённый `video/*` (обычно `video/mp4`), иначе `application/octet-stream`; `Content-Disposition: attachment`. Range-запросы не поддерживаются.


        Ролик хранится 72 часа с создания задачи. До готовности и после срока хранения — одинаково 404 `video_not_ready`. Подходит и ключ только для чтения.'
      security:
      - bearerAuth: []
      - oauth2:
        - videos:read
      parameters:
      - schema:
          type: string
          format: uuid
          description: Номер задачи из ответа `POST /v1/videos`.
        required: true
        name: id
        in: path
      - schema:
          type: integer
          minimum: 0
          maximum: 0
          default: 0
          description: Номер ролика задачи. В v1 у задачи один ролик — `0`; больше нуля — 400 `index_out_of_range`.
        required: false
        name: index
        in: query
      responses:
        '200':
          description: Ролик целиком.
          content:
            video/mp4:
              schema:
                type: string
                format: binary
        '400':
          description: Некорректный `index` (`invalid_request`) или больше нуля (`index_out_of_range`).
        '401':
          description: Ключ не передан, невалиден, отозван или заморожен (`invalid_api_key`, `key_frozen_spike`).
        '403':
          description: 'OAuth-токен без права `videos:read` (`insufficient_scope`). Ещё причины: management-ключ (`inference_key_required`), запрос не с адреса, к которому привязан ключ (`key_ip_not_allowed`), или заблокированный аккаунт (`account_blocked`).'
        '404':
          description: Задачи нет или она чужая (`not_found`); ролик ещё не готов или срок хранения истёк (`video_not_ready`).
  /v1/video/transcriptions:
    post:
      operationId: createVideoTranscription
      tags:
      - Videos
      summary: Расшифровать ролик YouTube по ссылке
      description: 'Дословная расшифровка с таймкодами (`exact`) или пересказ (`fast`) публичного ролика YouTube. Ролик по ссылке смотрит модель `google/gemini-3.8-flash`, скачивать видео не нужно. Не путать с `/v1/videos` — там генерация.


        До запроса к модели ролик проверяется: удалённый, приватный, открытый только по ссылке, прямой эфир и ролик длиннее 4 часов отклоняются без списания.


        Оплата по токенам, как у запроса к модели: `usage.cost` — сумма в копейках. Если ответ в режиме `exact` упирается в лимит длины, Hubris сам запрашивает продолжение и склеивает куски — до 5 запросов к модели (`usage.requests`). Стрима нет, ответ приходит целиком.


        Ошибки самого запроса к модели (402, 429, 5xx) приходят в том же виде, что у `/v1/chat/completions`.'
      security:
      - bearerAuth: []
      - oauth2:
        - chat:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoTranscriptionRequest'
      responses:
        '200':
          description: Расшифровка или пересказ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoTranscription'
        '400':
          description: Невалидный JSON (`invalid_json`) или параметр (`invalid_parameter`), ссылка не на ролик YouTube (`invalid_video_url`), прямой эфир или премьера (`video_is_live`), ролик длиннее 4 часов (`video_too_long`).
        '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: Ролик удалён, приватный или открыт только по ссылке (`video_unavailable`).
        '413':
          description: Тело запроса больше 64 КБ (`request_too_large`).
        '429':
          description: Исчерпан лимит расхода ключа (`daily_limit_exceeded`, `key_limit_exceeded`), лимит пространства (`workspace_limit_exceeded`) или провайдер временно ограничил запросы. Пауза — в `Retry-After`.
        '502':
          description: Сбой модели (`upstream_error`).
        '503':
          description: Проверка ролика временно недоступна (`video_lookup_unavailable`) или курс ЦБ РФ недоступен.
  /v1/videos/models:
    get:
      operationId: listVideoModels
      tags:
      - Videos
      summary: Каталог видео-моделей
      description: 'Активные видео-модели с ценами в рублях за единицу (секунда/видео).

        Цены провайдера в USD и внутренние SKU не раскрываются.'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Список видео-моделей.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoModelsList'
        '401':
          description: Невалидный или отсутствующий API-ключ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoModelsErrorResponse'
        '503':
          description: Не удалось получить курс ЦБ РФ — каталог временно недоступен.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoModelsErrorResponse'
components:
  schemas:
    VideoJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending
          - in_progress
          - completed
          - failed
        created:
          type: integer
          description: Время создания задачи, Unix-секунды.
        unsigned_urls:
          type: array
          items:
            type: string
            format: uri
          description: 'Только при `completed`: адрес скачивания `GET /v1/videos/{id}/content?index=0`. Несмотря на имя, нужен тот же ключ.'
        usage:
          type: object
          properties:
            cost:
              type: integer
              description: 'При `completed`: итоговое списание, копейки.'
            estimated_cost:
              type: integer
              description: 'Пока задача в работе: сумма, удержанная под задачу, копейки (верхняя оценка; если сверка прошла раньше готовности — уже списанная). После готовности приходит `cost`, разница возвращается на баланс.'
        error:
          type: string
          description: 'Только при `failed`: нейтральный текст. Удержание возвращается целиком.'
      required:
      - id
      - status
      - created
    VideoJobCreated:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Номер задачи.
          example: b0f2c1a4-3e9d-4b7a-9c2e-8f1a6d5c4b3a
        status:
          type: string
          enum:
          - pending
        polling_url:
          type: string
          format: uri
          description: Адрес опроса статуса — `GET /v1/videos/{id}`.
        created:
          type: integer
          description: Время создания задачи, Unix-секунды.
      required:
      - id
      - status
      - polling_url
      - created
    VideoModelsErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
      - error
    VideoTranscription:
      type: object
      properties:
        id:
          type: string
          example: vtr-3f9c1a7b2d4e5f60a1b2c3d4
        object:
          type: string
          enum:
          - video.transcription
        created:
          type: integer
          description: Unix-секунды.
        model:
          type: string
          description: Модель, которая смотрела ролик.
        video:
          type: object
          properties:
            id:
              type: string
              description: ID ролика на YouTube.
            title:
              type: string
            duration_sec:
              type: integer
          required:
          - id
          - title
          - duration_sec
        mode:
          type: string
          enum:
          - exact
          - fast
        diarize:
          type: boolean
          description: В режиме `fast` всегда `false`.
        text:
          type: string
          description: Расшифровка или пересказ.
        truncated:
          type: boolean
          description: '`true` — текст оборвался по лимиту длины ответа даже после продолжений, или продолжение не удалось и отдано собранное.'
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
            cost:
              type: integer
              description: Списано с баланса за все запросы к модели, копейки.
            requests:
              type: integer
              description: Сколько запросов к модели понадобилось.
          required:
          - prompt_tokens
          - completion_tokens
          - total_tokens
          - cost
          - requests
      required:
      - id
      - object
      - created
      - model
      - video
      - mode
      - diarize
      - text
      - truncated
      - usage
    VideoTranscriptionRequest:
      type: object
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 2000
          description: 'Ссылка на ролик YouTube: `youtube.com/watch?v=…`, `youtu.be/…`, `youtube.com/shorts/…`, `youtube.com/live/…`.'
          example: https://youtu.be/ITL6WqcV6sE
        mode:
          type: string
          enum:
          - exact
          - fast
          default: exact
          description: '`exact` — дословная расшифровка, каждая реплика с новой строки и таймкодом `[HH:MM:SS]`. `fast` — пересказ и ключевые мысли с таймкодами: быстрее и дешевле на длинном ролике, таймкоды приблизительные.'
        diarize:
          type: boolean
          default: false
          description: 'Только для `exact`: помечать реплики говорящими («Говорящий 1:» или имя, если оно звучит в ролике).'
      required:
      - url
    VideoFrameImage:
      type: object
      properties:
        type:
          type: string
          enum:
          - image_url
        image_url:
          type: object
          properties:
            url:
              type: string
              minLength: 1
          required:
          - url
          additionalProperties: false
        frame_type:
          type: string
          enum:
          - first_frame
          - last_frame
      required:
      - type
      - image_url
      - frame_type
      additionalProperties: false
    VideoModelsList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/VideoModel'
      required:
      - object
      - data
    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
    VideoModel:
      type: object
      properties:
        id:
          type: string
          example: kwaivgi/kling-v3.0-pro
        object:
          type: string
          enum:
          - video_model
        created:
          type: integer
          description: Unix-timestamp последнего обновления записи в каталоге Hubris.
        owned_by:
          type: string
          example: kwaivgi
        display_name:
          type: string
          example: Kling v3.0 Pro
        description:
          type: string
          nullable: true
          description: Описание модели на русском языке (если переведено).
        supported_resolutions:
          type: array
          items:
            type: string
          example:
          - 720p
          - 1080p
        supported_aspect_ratios:
          type: array
          items:
            type: string
          example:
          - '16:9'
          - '9:16'
        supported_sizes:
          type: array
          items:
            type: string
          example:
          - 1280x720
        supported_durations:
          type: array
          items:
            type: integer
          example:
          - 5
          - 8
        supported_frame_images:
          type: array
          items:
            type: string
          description: Какие опорные кадры принимает модель для image-to-video.
          example:
          - first_frame
        generate_audio:
          type: boolean
          description: Поддерживает ли модель генерацию звука.
        seed:
          type: boolean
          description: Поддерживает ли модель детерминированный seed.
        required_input:
          type: string
          nullable: true
          enum:
          - video
          - image
          description: 'Что модели обязательно передать в input_references: исходное видео или фото. null — вход не нужен.'
        upscale_factor:
          type: object
          nullable: true
          properties:
            min:
              type: number
            max:
              type: number
          required:
          - min
          - max
        creativity:
          type: object
          nullable: true
          properties:
            min:
              type: number
            max:
              type: number
          required:
          - min
          - max
        allowed_passthrough_parameters:
          type: array
          items:
            type: string
          description: Ключи, которые можно передать в provider.options.<поставщик>.parameters.
        pricing:
          type: object
          properties:
            per_unit:
              type: array
              items:
                type: object
                properties:
                  sku:
                    type: string
                    example: video
                  price_rub:
                    type: number
                    example: 10.33
                  unit:
                    type: string
                    example: second
                required:
                - sku
                - price_rub
                - unit
              description: Цены за единицу в рублях (секунда/видео). Цены провайдера в USD не раскрываются.
            currency:
              type: string
              enum:
              - RUB
          required:
          - per_unit
          - currency
      required:
      - id
      - object
      - created
      - owned_by
      - display_name
      - description
      - supported_resolutions
      - supported_aspect_ratios
      - supported_sizes
      - supported_durations
      - supported_frame_images
      - generate_audio
      - seed
      - required_input
      - upscale_factor
      - creativity
      - allowed_passthrough_parameters
      - pricing
    VideoInputReference:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - image_url
          image_url:
            type: object
            properties:
              url:
                type: string
                minLength: 1
            required:
            - url
            additionalProperties: false
        required:
        - type
        - image_url
        additionalProperties: false
      - type: object
        properties:
          type:
            type: string
            enum:
            - video_url
          video_url:
            type: object
            properties:
              url:
                type: string
                minLength: 1
                maxLength: 2048
            required:
            - url
            additionalProperties: false
        required:
        - type
        - video_url
        additionalProperties: false
    CreateVideoRequest:
      type: object
      properties:
        model:
          type: string
          minLength: 1
          maxLength: 200
          example: kwaivgi/kling-v3.0-pro
        prompt:
          type: string
          minLength: 1
          maxLength: 50000
        duration:
          type: integer
          minimum: 1
          maximum: 60
        resolution:
          type: string
          maxLength: 10
        aspect_ratio:
          type: string
          maxLength: 10
        size:
          type: string
          maxLength: 16
        generate_audio:
          type: boolean
        seed:
          type: integer
        frame_images:
          type: array
          items:
            $ref: '#/components/schemas/VideoFrameImage'
          maxItems: 2
        input_references:
          type: array
          items:
            $ref: '#/components/schemas/VideoInputReference'
          minItems: 1
          maxItems: 4
        upscale_factor:
          type: number
          minimum: 0
          exclusiveMinimum: true
        creativity:
          type: number
          minimum: 0
          maximum: 1
        provider:
          type: object
          properties:
            options:
              type: object
              additionalProperties:
                type: object
                properties:
                  parameters:
                    type: object
                    additionalProperties:
                      nullable: true
                required:
                - parameters
                additionalProperties: false
          required:
          - options
          additionalProperties: false
      required:
      - model
      - prompt
      additionalProperties: false
  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 дней без повторного входа.