# Voices

Discover voices and upload a private reference recording.

## GET /api/generate/voices

Requires **read** scope. Returns voice summaries with `id` and `name`, plus pagination data.

| Query | Default | Meaning |
| --- | --- | --- |
| `scope` | `mine` | Your owned private voices; `explore` lists approved public voices. |
| `page` | `1` | Integer 1–10,000. Pages contain up to 50 voices. |
| `language` | omitted | Optional supported voice language filter. |

```bash
curl 'https://letsgen.app/api/generate/voices?scope=explore&page=1' \
  -H "Authorization: Bearer $LETSGEN_API_KEY"
```

Use returned IDs in `parameters.voiceProfileId` for [speech](/docs/api/audio). Public catalog discovery does not make private voices public.

## POST /api/generate/voices

Requires **generate** scope. Send multipart form data:

| Field | Required | Meaning |
| --- | --- | --- |
| `file` | yes | MP3, WAV, OGG, M4A, AAC, FLAC, or WebM audio, 1 byte–50 MiB. |
| `duration` | yes | Recording duration in seconds, 15–300. |
| `rightsConfirmed` | yes | Literal string `true`, only after permission is confirmed. |

```bash
curl https://letsgen.app/api/generate/voices \
  -H "Authorization: Bearer $LETSGEN_API_KEY" \
  -F 'file=@reference.wav;type=audio/wav' \
  -F 'duration=30' \
  -F 'rightsConfirmed=true'
```

Let your HTTP client set the multipart boundary; do not set the Content-Type manually. Only attest rights when you own or have permission to clone the voice.

An accepted upload transcribes the recording and returns HTTP `201` with `{voice: {id, name}}`. The voice is an owned private draft for zero-shot cloning. This does not train or publish a voice, and does not start synthesis. Submit a separate audio request using the returned ID and `operation: "voice_clone"`.

Voice upload does not support generation idempotency. Transcription must succeed for the upload to finish; do not automatically repeat an uncertain upload.