neurall-io Voices API

openapi: 3.2.0
info:
  title: Neurall API (v3) Voices API
  version: 1.0.0
  description: 'The public v3 surface: /v3/generations for async generations that produce a content asset, /v3/voices for the voice catalog and your own cloned voices, plus file uploads, per-feature pricing, read-only templates, and signed webhooks. Authenticate every call with an API key in the Authorization header. This document is machine-readable at https://api.neurall.io/v3/openapi.json (import it into Postman, or generate a client).'
servers:
- url: https://api.neurall.io
tags:
- name: Voices
  description: The Neurall voice catalog and the project's own cloned voices (v3)
paths:
  /v3/voices:
    post:
      summary: Clone a Voice
      description: 'Clone a voice from an audio sample: upload about thirty seconds of clean speech to /v3/files/upload, then POST its file id here. Returns immediately with `status: running`; poll GET /v3/voices/{id} until it is `done`, or pass `webhookUrl` and be told.


        The id you get back IS the voiceId, usable in `args.voiceId` on audio/voiceover and video/avatar. Charged on submit like a generation, refunded on error or timeout. An organization may have 5 voices training at once.'
      security:
      - ApiKeyAuth: []
      tags:
      - Voices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name for the voice.
                audio:
                  type: string
                  description: File id of the audio sample, from POST /v3/files/upload. MP3, WAV, M4A, OGG, FLAC or WebM, holding a real audio stream.
                description:
                  type: string
                webhookUrl:
                  type: string
                  description: 'Optional https URL to POST the finished voice to (`voice.done` / `voice.error`), signed exactly like a generation webhook.

                    '
              required:
              - name
              - audio
      responses:
        '200':
          description: The voice, still training
          content:
            application/json:
              schema:
                type: object
                properties:
                  voice:
                    $ref: '#/components/schemas/Voice'
              example:
                voice:
                  id: d77c4b2e-5a90-4f13-b8c6-1e2f3a4b5c6d
                  owner: project
                  status: running
                  name: Founder voice
                  requestDate: '2026-08-25T17:04:12.000Z'
        '400':
          description: Missing name or audio, or the sample is too short
        '401':
          description: Unauthorized
        '402':
          description: Insufficient balance
        '429':
          description: Too many voices training at once (Retry-After header)
      operationId: postV3Voices
      x-operation-id-source: derived
    get:
      summary: List Voices
      description: 'Every voice this project can speak with: its own cloned voices first (`owner: project`), then the Neurall catalog (`owner: neurall`), which is ready-made and identical for every caller. Filter with `?owner=`.


        Pass a voice''s `id` (or a catalog `slug`, the stable handle worth hardcoding) as `args.voiceId` in an audio/voiceover or video/avatar generation. `preview` is a presigned audition clip on catalog voices and expires after ~6 hours; a clone carries a `status` instead, until it is `done`.'
      security:
      - ApiKeyAuth: []
      tags:
      - Voices
      parameters:
      - name: owner
        in: query
        required: false
        description: '`project` for this project''s own clones, `neurall` for the ready-made catalog. Omit for both. Anything else is a 400. `tag` and `locale` describe catalog rows only, so they are ignored on clones rather than silently hiding them.

          '
        schema:
          type: string
          enum:
          - neurall
          - project
      - name: tag
        in: query
        required: false
        description: 'Only voices carrying ALL of these tags. May repeat (?tag=female&tag=warm). Tags are lowercase descriptors: gender, age, accent, style, plus the category (narration, conversational, character, creature).

          '
        schema:
          type: array
          items:
            type: string
      - name: locale
        in: query
        required: false
        description: 'Only voices recorded for one locale, matched exactly against the voice''s own `locale` (e.g. `en-US`). It is not a prefix: `en` returns nothing.'
        schema:
          type: string
      - name: favorites
        in: query
        required: false
        description: Only the voices this project has starred. Accepts 1, true or yes.
        schema:
          type: string
      responses:
        '200':
          description: This project's clones, then the published catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  voices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Voice'
              example:
                voices:
                - id: d77c4b2e-5a90-4f13-b8c6-1e2f3a4b5c6d
                  owner: project
                  status: done
                  name: Founder voice
                - id: 5b3a9d10-2c47-4e8f-a6b1-9d0c3e7f2a84
                  owner: neurall
                  slug: aria
                  name: Aria
                  tags:
                  - female
                  - warm
                  - narration
                  locale: en-US
                  favorite: false
                  preview: https://cdn.neurall.io/…/aria-preview.mp3
        '401':
          description: Unauthorized
      operationId: getV3Voices
      x-operation-id-source: derived
  /v3/voices/{id}:
    get:
      summary: Get Voice
      description: 'Resolves ONE voice without pulling the whole list: a catalog voice by uuid or by slug, or one of this project''s own clones by its id. The shapes cannot collide, so a caller holding a voiceId never has to know which kind it is holding.


        On a clone this is the poll: after POST /v3/voices it answers `status: running` until the voice is `done` (or `error`), which is the same loop a generation uses.


        On a catalog voice there are two reasons to reach for it. First, `preview` is a presigned audition clip that expires after about 6 hours, so this is how you refresh the sample for a voice your app already knows about and lets a user play. Second, it is the cheap way to confirm a slug you hardcoded is still published: a retired voice answers 404 here rather than failing later, inside a generation you have already paid for.'
      security:
      - ApiKeyAuth: []
      tags:
      - Voices
      parameters:
      - name: id
        in: path
        required: true
        description: A catalog voice's uuid or slug, or one of this project's clone ids.
        schema:
          type: string
      responses:
        '200':
          description: The voice
          content:
            application/json:
              schema:
                type: object
                properties:
                  voice:
                    $ref: '#/components/schemas/Voice'
              example:
                voice:
                  id: d77c4b2e-5a90-4f13-b8c6-1e2f3a4b5c6d
                  owner: project
                  status: done
                  name: Founder voice
                  requestDate: '2026-08-25T17:04:12.000Z'
                  responseDate: '2026-08-25T17:09:35.000Z'
        '401':
          description: Unauthorized
        '404':
          description: Voice not found
      operationId: getV3VoicesById
      x-operation-id-source: derived
    delete:
      summary: Delete a Voice
      description: 'Delete one of this project''s cloned voices. It stops resolving everywhere, so anything still passing that id as `args.voiceId` starts failing, and there is no undelete: cloning again is a new generation. Catalog voices are not deletable.'
      security:
      - ApiKeyAuth: []
      tags:
      - Voices
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
              example:
                success: true
        '401':
          description: Unauthorized
        '404':
          description: Not one of this project's cloned voices
      operationId: deleteV3VoicesById
      x-operation-id-source: derived
  /v3/voices/{id}/favorite:
    put:
      summary: Favorite Voice
      description: 'Star a catalog voice for the calling PROJECT (not the user, so a team shares one shortlist). Idempotent: starring twice is one row. The catalog row itself is unchanged for everyone else; `favorite` is computed per request.'
      security:
      - ApiKeyAuth: []
      tags:
      - Voices
      parameters:
      - name: id
        in: path
        required: true
        description: The voice's uuid or its slug.
        schema:
          type: string
      responses:
        '200':
          description: The favorite state after the call
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  favorite:
                    type: boolean
        '401':
          description: Unauthorized
        '404':
          description: Voice not found
      operationId: putV3VoicesByIdFavorite
      x-operation-id-source: derived
    delete:
      summary: Unfavorite Voice
      description: Unstar a catalog voice for the calling project. Idempotent.
      security:
      - ApiKeyAuth: []
      tags:
      - Voices
      parameters:
      - name: id
        in: path
        required: true
        description: The voice's uuid or its slug.
        schema:
          type: string
      responses:
        '200':
          description: The favorite state after the call
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  favorite:
                    type: boolean
        '401':
          description: Unauthorized
        '404':
          description: Voice not found
      operationId: deleteV3VoicesByIdFavorite
      x-operation-id-source: derived
components:
  schemas:
    Voice:
      type: object
      description: 'A voice this project can speak with. `owner: neurall` is a catalog voice, ready to use and identical for every caller. `owner: project` is one of the project''s own clones, which carries the same status lifecycle as a Generation while it trains. A voice''s own id is what goes in `args.voiceId`.

        '
      properties:
        id:
          type: string
        owner:
          type: string
          enum:
          - neurall
          - project
        status:
          type: string
          enum:
          - running
          - done
          - error
        name:
          type: string
        description:
          type: string
        slug:
          type: string
          description: Catalog voices only. Stable handle, safe to hardcode; accepted anywhere the uuid is.
        tags:
          type: array
          description: 'Catalog voices only. Lowercase descriptors: gender, age, accent, style, plus the category (narration, conversational, character, creature).'
          items:
            type: string
        locale:
          type: string
          description: Catalog voices only
        favorite:
          type: boolean
          description: Catalog voices only, whether this project starred it
        preview:
          type: string
          description: Catalog voices only, a presigned audition clip (expires after ~6 hours)
        error:
          type: string
        requestDate:
          type: string
        responseDate:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization