Hubris Usage API

openapi: 3.2.0
info:
  title: Hubris Usage 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: Usage
paths:
  /v1/usage:
    get:
      operationId: getUsage
      tags:
      - Usage
      summary: Расход по API-ключу за период
      description: Возвращает итоговые расходы (рубли + копейки + токены + количество запросов) по тому API-ключу, которым сделан запрос; OAuth-токену — по всему подключению приложения (токен меняется каждый час, сумма — по всем токенам подключения). По умолчанию — последние 24 часа. Можно передать шорткат `?period=` либо явные `?from=&to=` (ISO 8601, UTC). Опциональный `?granularity=` добавит массив `buckets` для построения графика.
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          enum:
          - today
          - 24h
          - 7d
          - 30d
          - mtd
          description: Шорткат периода. `today` = с 00:00 UTC текущих суток. `24h` = последние 24ч. `7d`/`30d` = последние N суток. `mtd` = с 1-го числа текущего месяца UTC. Несовместим с `from`/`to`.
        required: false
        name: period
        in: query
      - schema:
          type: string
          format: date-time
          description: Начало периода, ISO 8601. Если задан — `to` тоже обязателен.
        required: false
        name: from
        in: query
      - schema:
          type: string
          format: date-time
          description: Конец периода, ISO 8601. Если задан — `from` тоже обязателен.
        required: false
        name: to
        in: query
      - schema:
          type: string
          enum:
          - hour
          - day
          description: Если указан — в ответе появится массив `buckets` с агрегатами по этому шагу.
        required: false
        name: granularity
        in: query
      - schema:
          type: string
          format: uuid
          description: 'Только management-ключом: сузить аккаунт-скоуп до одного API-ключа.'
        required: false
        name: key_id
        in: query
      - schema:
          type: string
          enum:
          - key
          - model
          description: 'Только management-ключом: добавить разбивку `by_key` или `by_model`.'
        required: false
        name: group_by
        in: query
      responses:
        '200':
          description: Расход по ключу за указанный период.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '400':
          description: Невалидные параметры периода (range_invalid / range_too_long / period_invalid).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageErrorResponse'
        '401':
          description: Невалидный или отсутствующий API-ключ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageErrorResponse'
        '429':
          description: Превышен дневной лимит ключа.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageErrorResponse'
components:
  schemas:
    UsageGranularity:
      type: string
      nullable: true
      enum:
      - hour
      - day
      description: Если `granularity` был задан, тут он же. Иначе null.
    UsageErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
      - error
    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
    UsagePeriod:
      type: string
      nullable: true
      enum:
      - today
      - 24h
      - 7d
      - 30d
      - mtd
      description: Шорткат, если запрос был сделан через `?period=`. Иначе null.
    UsageBucket:
      type: object
      properties:
        bucket:
          type: string
          format: date-time
          description: Начало интервала в ISO 8601 (UTC).
          example: '2026-05-14T00:00:00.000Z'
        cost_rub:
          type: number
          description: Стоимость за интервал в рублях. cost_kopecks/100.
          example: 12.34
        cost_kopecks:
          type: string
          description: Стоимость за интервал в копейках (строка — чтобы пережить JSON без потери точности).
          example: '1234'
        requests:
          type: integer
          minimum: 0
          example: 42
      required:
      - bucket
      - cost_rub
      - cost_kopecks
      - requests
    UsageResponse:
      type: object
      properties:
        object:
          type: string
          enum:
          - usage
        period:
          type: object
          properties:
            from:
              type: string
              format: date-time
              description: Начало периода (UTC, ISO 8601). Включительно.
              example: '2026-05-13T00:00:00.000Z'
            to:
              type: string
              format: date-time
              description: Конец периода (UTC, ISO 8601). Включительно.
              example: '2026-05-14T00:00:00.000Z'
            shortcut:
              $ref: '#/components/schemas/UsagePeriod'
          required:
          - from
          - to
          - shortcut
        scope:
          anyOf:
          - type: object
            properties:
              key_id:
                type: string
                format: uuid
              key_prefix:
                type: string
                example: sk-gw-a1b2...c3d4
            required:
            - key_id
            - key_prefix
          - type: object
            properties:
              account:
                type: boolean
                enum:
                - true
              key_id:
                type: string
                nullable: true
                format: uuid
            required:
            - account
            - key_id
          description: 'Обычный ключ: расход только по нему. OAuth-токен: расход всего подключения приложения, `key_id` — текущий токен. Management-ключ: весь аккаунт (`account: true`), опционально суженный параметром `key_id`.'
        totals:
          type: object
          properties:
            requests:
              type: integer
              minimum: 0
              example: 137
            prompt_tokens:
              type: integer
              minimum: 0
              description: Новые токены входа, без кеша.
              example: 6000
            completion_tokens:
              type: integer
              minimum: 0
              example: 130
            input_tokens_total:
              type: integer
              minimum: 0
              description: 'Весь вход: prompt_tokens + cache_read_tokens + cache_write_tokens.'
              example: 204000
            total_tokens:
              type: integer
              minimum: 0
              description: 'Все токены периода: input_tokens_total + completion_tokens.'
              example: 204130
            cost_rub:
              type: number
              description: Итоговая стоимость за период в рублях. Эквивалент cost_kopecks/100.
              example: 42.17
            cost_kopecks:
              type: string
              description: Итоговая стоимость в копейках (строка для точности при сериализации bigint).
              example: '4217'
            cache_read_tokens:
              type: integer
            cache_write_tokens:
              type: integer
            reasoning_tokens:
              type: integer
            cache_hit_rate:
              type: number
            cache_savings_kopecks:
              type: string
            cache_savings_rub:
              type: number
          required:
          - requests
          - prompt_tokens
          - completion_tokens
          - input_tokens_total
          - total_tokens
          - cost_rub
          - cost_kopecks
          - cache_read_tokens
          - cache_write_tokens
          - reasoning_tokens
          - cache_hit_rate
          - cache_savings_kopecks
          - cache_savings_rub
        granularity:
          $ref: '#/components/schemas/UsageGranularity'
        buckets:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/UsageBucket'
          description: Точки графика. Null, если `granularity` не запрошен.
        by_key:
          type: array
          nullable: true
          items:
            type: object
            properties:
              key_id:
                type: string
                nullable: true
                format: uuid
              key_prefix:
                type: string
                nullable: true
              name:
                type: string
                nullable: true
              requests:
                type: integer
                minimum: 0
              total_tokens:
                type: integer
                minimum: 0
                description: Весь вход с кешем + выход.
              cost_kopecks:
                type: string
                description: Копейки строкой — как в totals.
                example: '1234'
            required:
            - key_id
            - key_prefix
            - name
            - requests
            - total_tokens
            - cost_kopecks
          description: Разбивка по ключам аккаунта (`group_by=key`, только management-ключом). Иначе отсутствует.
        by_model:
          type: array
          nullable: true
          items:
            type: object
            properties:
              model:
                type: string
              requests:
                type: integer
                minimum: 0
              prompt_tokens:
                type: integer
                minimum: 0
                description: Новые токены входа, без кеша.
              completion_tokens:
                type: integer
                minimum: 0
              cache_read_tokens:
                type: integer
                minimum: 0
              cache_write_tokens:
                type: integer
                minimum: 0
              input_tokens_total:
                type: integer
                minimum: 0
                description: Весь вход с кешем.
              total_tokens:
                type: integer
                minimum: 0
                description: input_tokens_total + completion_tokens.
              cost_kopecks:
                type: string
                description: Копейки строкой — как в totals.
                example: '1234'
            required:
            - model
            - requests
            - prompt_tokens
            - completion_tokens
            - cache_read_tokens
            - cache_write_tokens
            - input_tokens_total
            - total_tokens
            - cost_kopecks
          description: Разбивка по моделям (`group_by=model`, только management-ключом). Иначе отсутствует.
      required:
      - object
      - period
      - scope
      - totals
      - granularity
      - buckets
  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 дней без повторного входа.