Ditto Audio Admin/models API

openapi: 3.2.0
info:
  title: ditto.audio Admin/models 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: admin/models
  description: Admin — manage voice models & uploads
paths:
  /v1/admin/models/{id}/translations:
    get:
      operationId: AdminModelsController_listTranslations
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: A voice's translations, each saying whether it still matches the English…
      tags:
      - admin/models
  /v1/admin/models/{id}/translations/{locale}:
    put:
      description: '`source` is the English it was made from and must be the voice''s current description (409 otherwise): a translation is served only while its English is current.'
      operationId: AdminModelsController_putTranslation
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: locale
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutVoiceTranslationDto'
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Write the voice's description in one of the site's languages
      tags:
      - admin/models
    delete:
      operationId: AdminModelsController_deleteTranslation
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: locale
        required: true
        in: path
        schema:
          type: string
      - name: field
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Remove one translation (the page then shows the English)
      tags:
      - admin/models
  /v1/admin/models:
    post:
      operationId: AdminModelsController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVoiceModelDto'
      responses:
        '201':
          description: ''
      security:
      - bearer: []
      summary: Create a model (draft)
      tags:
      - admin/models
    get:
      operationId: AdminModelsController_list
      parameters:
      - name: page
        required: true
        in: query
        schema:
          type: string
      - name: limit
        required: true
        in: query
        schema:
          type: string
      - name: q
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: List all models (any status)
      tags:
      - admin/models
  /v1/admin/models/{id}:
    get:
      operationId: AdminModelsController_findOne
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Get a model with its full file list
      tags:
      - admin/models
    patch:
      operationId: AdminModelsController_update
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVoiceModelDto'
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Update model metadata
      tags:
      - admin/models
    delete:
      operationId: AdminModelsController_remove
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      security:
      - bearer: []
      summary: Delete a model and all its files (incl. blobs)
      tags:
      - admin/models
  /v1/admin/models/{id}/status:
    patch:
      operationId: AdminModelsController_setStatus
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetModelStatusDto'
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Publish / suspend / draft a model
      tags:
      - admin/models
  /v1/admin/models/{id}/files/presign:
    post:
      operationId: AdminModelsController_presign
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PresignUploadDto'
      responses:
        '201':
          description: ''
      security:
      - bearer: []
      summary: Reserve a key + presigned PUT URL for a big file
      tags:
      - admin/models
  /v1/admin/models/{id}/files/confirm:
    post:
      operationId: AdminModelsController_confirm
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmUploadDto'
      responses:
        '201':
          description: ''
      security:
      - bearer: []
      summary: Confirm a presigned upload landed (records size)
      tags:
      - admin/models
  /v1/admin/models/{id}/files:
    post:
      operationId: AdminModelsController_uploadSmall
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadSmallFileDto'
      responses:
        '201':
          description: ''
      security:
      - bearer: []
      summary: Stream-upload a small file (≤25MB) through the API
      tags:
      - admin/models
  /v1/admin/models/{id}/files/{fileId}:
    delete:
      operationId: AdminModelsController_removeFile
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: fileId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      security:
      - bearer: []
      summary: Delete one file (incl. blob)
      tags:
      - admin/models
components:
  schemas:
    UpdateVoiceModelDto:
      type: object
      properties:
        slug:
          type: string
          example: en-us-amy-medium
          description: lowercase-kebab unique id
        name:
          type: string
          example: Amy (US English, Medium)
        description:
          type: string
        engine:
          type: string
          enum:
          - piper
          - xtts
          - kokoro
          - pocket
          - rvc
          - system
          - morpho
        language:
          type: string
          example: en-US
        quality:
          type: string
          example: medium
        gender:
          type: object
          example: female
          description: 'Who the voice sounds like: `female`, `male` or `neutral`. A label or alias (`woman`, `man`) is stored as its key; a word that names none is a 400 `VOICE_TAXONOMY`, like every word of the voice taxonomy.'
        accent:
          type: object
          example: en-scottish
          description: 'An accent of the voice taxonomy (GET /v1/models/taxonomy), when finer than what `language` says: `en-GB` is British already.'
        age:
          type: object
          example: young
          description: 'How old the voice sounds: `young`, `middle-aged` or `older` (a label is stored as its key).'
        styles:
          example:
          - warm
          - calm
          description: 'How it sounds: style keys of the voice taxonomy.'
          type: array
          items:
            type: string
        useCases:
          example:
          - narration
          description: 'What it suits: use-case keys of the voice taxonomy.'
          type: array
          items:
            type: string
        taxonomySource:
          type: string
          enum:
          - curated
          - measured
          - import
          default: curated
          description: 'Who says the accent, styles and use cases of this request: the catalogue''s record, a measurement of the audio, or the dataset the voice came from.'
        version:
          type: string
          example: 1.0.0
        format:
          type: string
          example: onnx
        sampleRate:
          type: number
          example: 22050
        author:
          type: string
        license:
          type: string
          example: MIT
        sourceUrl:
          type: string
        tags:
          type: array
          items:
            type: string
        coverImageUrl:
          type: string
        isPublic:
          type: boolean
          default: true
        isFeatured:
          type: boolean
          default: false
        isPremium:
          type: boolean
          default: false
          description: Premium voice — access gated by the subscriber tier quota (premiumModels).
        baseSlug:
          type: string
          example: xtts-v2
          description: 'For an overlay catalog voice (e.g. an XTTS studio speaker): the slug of the base XTTS voice whose heavy bundle this voice reuses. Only this voice’s latents are stored; the client loads the shared base and swaps them in.'
    PutVoiceTranslationDto:
      type: object
      properties:
        field:
          type: string
          enum:
          - description
          default: description
        value:
          type: string
          description: The text in that language.
        source:
          type: string
          description: 'The English it was translated from: must be the voice''s current text (409 otherwise).'
        translatedBy:
          type: string
          description: 'Who made it: ''human'' (default) or ''machine:<tool>''.'
      required:
      - value
      - source
    UploadSmallFileDto:
      type: object
      properties:
        role:
          type: string
          enum:
          - model
          - config
          - vocab
          - speakers
          - index
          - sample
          - archive
          - other
        fileName:
          type: string
          description: override stored filename
      required:
      - role
    SetModelStatusDto:
      type: object
      properties:
        status:
          type: string
          enum:
          - draft
          - published
          - suspended
      required:
      - status
    PresignUploadDto:
      type: object
      properties:
        fileName:
          type: string
          example: model.onnx
        role:
          type: string
          enum:
          - model
          - config
          - vocab
          - speakers
          - index
          - sample
          - archive
          - other
        contentType:
          type: string
          example: application/octet-stream
      required:
      - fileName
      - role
    CreateVoiceModelDto:
      type: object
      properties:
        slug:
          type: string
          example: en-us-amy-medium
          description: lowercase-kebab unique id
        name:
          type: string
          example: Amy (US English, Medium)
        description:
          type: string
        engine:
          type: string
          enum:
          - piper
          - xtts
          - kokoro
          - pocket
          - rvc
          - system
          - morpho
        language:
          type: string
          example: en-US
        quality:
          type: string
          example: medium
        gender:
          type: object
          example: female
          description: 'Who the voice sounds like: `female`, `male` or `neutral`. A label or alias (`woman`, `man`) is stored as its key; a word that names none is a 400 `VOICE_TAXONOMY`, like every word of the voice taxonomy.'
        accent:
          type: object
          example: en-scottish
          description: 'An accent of the voice taxonomy (GET /v1/models/taxonomy), when finer than what `language` says: `en-GB` is British already.'
        age:
          type: object
          example: young
          description: 'How old the voice sounds: `young`, `middle-aged` or `older` (a label is stored as its key).'
        styles:
          example:
          - warm
          - calm
          description: 'How it sounds: style keys of the voice taxonomy.'
          type: array
          items:
            type: string
        useCases:
          example:
          - narration
          description: 'What it suits: use-case keys of the voice taxonomy.'
          type: array
          items:
            type: string
        taxonomySource:
          type: string
          enum:
          - curated
          - measured
          - import
          default: curated
          description: 'Who says the accent, styles and use cases of this request: the catalogue''s record, a measurement of the audio, or the dataset the voice came from.'
        version:
          type: string
          example: 1.0.0
        format:
          type: string
          example: onnx
        sampleRate:
          type: number
          example: 22050
        author:
          type: string
        license:
          type: string
          example: MIT
        sourceUrl:
          type: string
        tags:
          type: array
          items:
            type: string
        coverImageUrl:
          type: string
        isPublic:
          type: boolean
          default: true
        isFeatured:
          type: boolean
          default: false
        isPremium:
          type: boolean
          default: false
          description: Premium voice — access gated by the subscriber tier quota (premiumModels).
        baseSlug:
          type: string
          example: xtts-v2
          description: 'For an overlay catalog voice (e.g. an XTTS studio speaker): the slug of the base XTTS voice whose heavy bundle this voice reuses. Only this voice’s latents are stored; the client loads the shared base and swaps them in.'
      required:
      - slug
      - name
      - engine
    ConfirmUploadDto:
      type: object
      properties:
        s3Key:
          type: string
          description: s3Key returned by the presign call
        sha256:
          type: string
          description: hex sha-256 for integrity
      required:
      - s3Key
  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.