Voices

List Voices

GET /v3/voices

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`.

curl -X GET "https://api.neurall.io/v3/voices" \
  -H "Authorization: nl-YOUR_API_KEY"

{
  "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"
    }
  ]
}

Clone a Voice

POST /v3/voices

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.

curl -X POST "https://api.neurall.io/v3/voices" \
  -H "Authorization: nl-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<name>",
    "audio": "<audio>",
    "description": "<description>",
    "webhookUrl": "<webhookUrl>"
  }'

{
  "voice": {
    "id": "d77c4b2e-5a90-4f13-b8c6-1e2f3a4b5c6d",
    "owner": "project",
    "status": "running",
    "name": "Founder voice",
    "requestDate": "2026-08-25T17:04:12.000Z"
  }
}

Get Voice

GET /v3/voices/{id}

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.

curl -X GET "https://api.neurall.io/v3/voices/<id>" \
  -H "Authorization: nl-YOUR_API_KEY"

{
  "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"
  }
}

Delete a Voice

DELETE /v3/voices/{id}

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.

curl -X DELETE "https://api.neurall.io/v3/voices/<id>" \
  -H "Authorization: nl-YOUR_API_KEY"

{
  "success": true
}