Ditto Audio Usage API

openapi: 3.2.0
info:
  title: ditto.audio Usage API
  description: Cloud API behind ditto.audio. The reader (reader.ditto.audio) and the voice studio (studio.ditto.audio) are separate apps sharing this one backend — see /docs/reader and /docs/inference for each app’s public surface. Third-party integrations want /docs/public (rendered for humans at https://ditto.audio/docs).
  version: '1.0'
  contact: {}
servers: []
tags:
- name: Usage
  description: Your own API usage & analytics — totals, time series and recent requests
paths:
  /v1/usage/quota:
    get:
      description: 'The allowance is BILLED SECONDS, and each model spends it at its own rate: a second of Kokoro costs 1.5, a second of XTTS costs 3. So there is one `percentUsed`, and `byModel[].remainingSeconds` says how much audio the remainder buys in each model — those are ALTERNATIVES drawn from the same pot, not separate budgets.


        `limitSeconds` and `remainingSeconds` are `null` when the account is unmetered. Exceeding the allowance answers `402 QUOTA_EXCEEDED` — deliberately not 429, because waiting does not help until `resetsAt`.


        The aggregate numbers ride on every synthesis response as `X-Ditto-Quota-*` headers, so an integration can watch its own headroom without polling this.'
      operationId: UsageController_quotaStatus
      parameters: []
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: 'Your monthly allowance: limit, used, remaining, percent, and what it buys per…'
      tags:
      - Usage
  /v1/usage/summary:
    get:
      description: Totals, month-to-date spend, and breakdowns by model, language and API key, with p50/p95 latency. Defaults to the last 30 days.
      operationId: UsageController_summary
      parameters:
      - name: to
        required: false
        in: query
        description: ISO-8601. Defaults to now.
        schema: {}
      - name: from
        required: false
        in: query
        description: ISO-8601. Defaults to 30 days ago.
        schema: {}
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Usage totals for a window, plus month-to-date and breakdowns
      tags:
      - Usage
  /v1/usage/timeseries:
    get:
      description: One point per hour or day across the whole window — idle buckets are returned as zeros so charts do not interpolate across quiet periods.
      operationId: UsageController_timeseries
      parameters:
      - name: bucket
        required: false
        in: query
        schema:
          enum:
          - hour
          - day
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Bucketed usage over time (gap-filled)
      tags:
      - Usage
  /v1/usage/recent:
    get:
      operationId: UsageController_recent
      parameters: []
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Your most recent API requests (including failures)
      tags:
      - Usage
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: ditto_sk_live_… API key, ditto_oat_… OAuth access token, or a session JWT
      type: http
      description: An API key (`ditto_sk_live_…`, made at https://ditto.audio/account/api-keys) authenticates /v1/audio/* and /v1/reader/*; an OAuth connection's one-hour access token (`ditto_oat_…`) holds the audio:read and audio:speech scopes only. Account routes (/v1/api-keys, /v1/usage, /v1/subscription) take the signed-in session's token (a JWT) only.