# polymorfa voice

> Voice Automation (beta): audio library and text-to-speech provider credentials.

## Commands

- [polymorfa voice audio delete](https://docs.polymorfa.com/cli/voice/audio-delete): Delete audio (beta).
- [polymorfa voice audio list](https://docs.polymorfa.com/cli/voice/audio-list): List audio (beta).
- [polymorfa voice audio preview](https://docs.polymorfa.com/cli/voice/audio-preview): Get a preview link for audio (beta).
- [polymorfa voice audio tts](https://docs.polymorfa.com/cli/voice/audio-tts): Create audio from text to speech (beta).
- [polymorfa voice audio update](https://docs.polymorfa.com/cli/voice/audio-update): Change audio (beta).
- [polymorfa voice audio upload](https://docs.polymorfa.com/cli/voice/audio-upload): Upload an audio file (beta).
- [polymorfa voice audio view](https://docs.polymorfa.com/cli/voice/audio-view): Show audio (beta).
- [polymorfa voice credential add](https://docs.polymorfa.com/cli/voice/credential-add): Store a provider key (beta).
- [polymorfa voice credential delete](https://docs.polymorfa.com/cli/voice/credential-delete): Delete a provider credential (beta).
- [polymorfa voice credential list](https://docs.polymorfa.com/cli/voice/credential-list): List provider credentials (beta).
- [polymorfa voice credential verify](https://docs.polymorfa.com/cli/voice/credential-verify): Check a provider credential again (beta).
- [polymorfa voice credential view](https://docs.polymorfa.com/cli/voice/credential-view): Show a provider credential (beta).

## polymorfa voice audio delete

Delete audio (beta).

Delete an audio asset permanently. Fails with voice_asset_in_use (exit code 4) while a campaign or flow uses it. Works after the Voice Automation beta is withdrawn. Requires a server API key with voice:manage.

### Usage

```bash
polymorfa voice audio delete ASSET [flags]
```

### Arguments

- `ASSET` (required). Audio asset ID.

### Flags

- `--yes` (boolean). Confirm permanent deletion without prompting.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

## polymorfa voice audio list

List audio (beta).

List the project's audio library, newest first. Requires a server API key with voice:read. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice audio list [flags]
```

### Flags

- `--cursor <value>` (value). Continue from this opaque cursor.
- `--limit <value>` (value). Return at most this many assets (1 to 100; API default 50).
- `--status <value>` (value). Only list assets with this status. Values: `pending_upload`, `uploaded`, `transcoding`, `ready`, `failed`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa voice audio list --project 018f0000-0000-7000-8000-000000000002
```

```bash
polymorfa voice audio list --status ready --limit 100 --project 018f0000-0000-7000-8000-000000000002
```

## polymorfa voice audio preview

Get a preview link for audio (beta).

Print a link to the transcoded audio (Opus in Ogg, 16 kHz mono). The link works for 5 minutes; treat it as a secret. --output downloads it instead of printing it. Fails with asset_not_ready (exit code 4) before the asset is ready. Requires a server API key with voice:read. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice audio preview ASSET [flags]
```

### Arguments

- `ASSET` (required). Audio asset ID.

### Flags

- `--force` (boolean). Overwrite an existing output file.
- `-o, --output <value>` (value). Download the preview to this file.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa voice audio preview 6f1c2f0e-1d5b-4d8e-9a55-0d4b8a6c1f10
```

```bash
polymorfa voice audio preview 6f1c2f0e-1d5b-4d8e-9a55-0d4b8a6c1f10 --output greeting.ogg
```

## polymorfa voice audio tts

Create audio from text to speech (beta).

Render text to speech into a new library asset. Without --credential, Polymorfa's managed key for the provider is used; with it, your stored provider credential for the same provider. Text is 1 to 5000 characters (4096 for openai). OpenAI voices: alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse. ElevenLabs takes a voice ID. Models: elevenlabs eleven_multilingual_v2 (default), eleven_flash_v2_5, eleven_turbo_v2_5; openai gpt-4o-mini-tts (default), tts-1, tts-1-hd. Requires a server API key with voice:manage. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice audio tts [flags]
```

### Flags

- `--credential <value>` (value). Use this stored provider credential instead of the managed key.
- `--model <value>` (value). Provider model; the provider's default when omitted.
- `--name <value>` (value, required). Name shown in the library (1 to 100 characters).
- `--provider <value>` (value, required). Text-to-speech provider. Values: `elevenlabs`, `openai`.
- `--retention-days <value>` (value). Delete the audio this many days after creation (1 to 3650). Omit to keep it until deleted.
- `--text <value>` (value). Text to speak.
- `--text-file <value>` (value). Read the text from a UTF-8 file, or stdin (-).
- `--voice <value>` (value, required). OpenAI voice name or ElevenLabs voice ID.
- `--wait` (boolean). Wait until the audio is ready or failed. A failed asset exits with code 13.
- `--wait-timeout <value>` (value). Stop waiting after this many seconds (exit code 5). Default: `120`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa voice audio tts --name "Welcome" --text "Thanks for calling." --provider openai --voice alloy --project 018f0000-0000-7000-8000-000000000002
```

```bash
polymorfa voice audio tts --name "Menu" --text-file menu.txt --provider elevenlabs --voice 21m00Tcm4TlvDq8ikWAM --credential 6f1c2f0e-1d5b-4d8e-9a55-0d4b8a6c1f10 --wait --project 018f0000-0000-7000-8000-000000000002
```

## polymorfa voice audio update

Change audio (beta).

Rename an audio asset or change how long it is kept. --expected-revision refuses the change with voice_asset_revision_conflict (exit code 4) if the asset changed. Requires a server API key with voice:manage. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice audio update ASSET [flags]
```

### Arguments

- `ASSET` (required). Audio asset ID.

### Flags

- `--expected-revision <value>` (value). Refuse the change if the asset no longer has this revision.
- `--name <value>` (value). New name (1 to 100 characters).
- `--retention-days <value>` (value). Days to keep the audio after creation (1 to 3650), or none to keep it until deleted.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa voice audio update 6f1c2f0e-1d5b-4d8e-9a55-0d4b8a6c1f10 --name "Greeting v2" --expected-revision 2
```

```bash
polymorfa voice audio update 6f1c2f0e-1d5b-4d8e-9a55-0d4b8a6c1f10 --retention-days none
```

## polymorfa voice audio upload

Upload an audio file (beta).

Upload a recording to the project's audio library. The content type comes from the file extension; other types and files over 16 MB are refused before anything is sent. The asset is returned while it is transcoded to 16 kHz mono; pass --wait to wait until it is ready or failed. Requires a server API key with voice:manage. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice audio upload FILE [flags]
```

### Arguments

- `FILE` (required). Audio file: .mp3, .wav, .ogg, .opus, .m4a or .mp4, at most 16 MB.

### Flags

- `--name <value>` (value, required). Name shown in the library (1 to 100 characters).
- `--retention-days <value>` (value). Delete the audio this many days after creation (1 to 3650). Omit to keep it until deleted.
- `--wait` (boolean). Wait until the audio is ready or failed. A failed asset exits with code 13.
- `--wait-timeout <value>` (value). Stop waiting after this many seconds (exit code 5). Default: `120`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa voice audio upload greeting.mp3 --name "Greeting" --project 018f0000-0000-7000-8000-000000000002
```

```bash
polymorfa voice audio upload hold.wav --name "Hold music" --retention-days 30 --wait --project 018f0000-0000-7000-8000-000000000002
```

## polymorfa voice audio view

Show audio (beta).

Show one audio asset, including its status, failure reason and revision. Requires a server API key with voice:read. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice audio view ASSET [flags]
```

### Arguments

- `ASSET` (required). Audio asset ID.

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

## polymorfa voice credential add

Store a provider key (beta).

Store your own ElevenLabs or OpenAI key for text to speech. The key is read from the environment variable named by --key-env (default POLYMORFA_VOICE_PROVIDER_KEY) or, when that is unset, from standard input; never from an argument. The provider checks the key first; a rejected key fails with provider_credential_invalid (exit code 2). Only the key's fingerprint is ever shown. With --project the credential belongs to that project; without it, every project of the team can use it. Requires a server API key with voice:manage. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice credential add [flags]
```

### Flags

- `--key-env <value>` (value). Read the key from this environment variable (default POLYMORFA_VOICE_PROVIDER_KEY; standard input when that is unset).
- `--label <value>` (value, required). Label shown in lists (1 to 100 characters).
- `--provider <value>` (value, required). Provider the key belongs to. Values: `elevenlabs`, `openai`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
printf '%s' "$ELEVENLABS_API_KEY" | polymorfa voice credential add --provider elevenlabs --label "Studio key"
```

```bash
POLYMORFA_VOICE_PROVIDER_KEY="$OPENAI_API_KEY" polymorfa voice credential add --provider openai --label "Support line" --project 018f0000-0000-7000-8000-000000000002
```

```bash
polymorfa voice credential add --provider openai --label "CI" --key-env OPENAI_API_KEY
```

## polymorfa voice credential delete

Delete a provider credential (beta).

Delete a stored provider key. Text to speech that names it then fails; audio already created is kept. Works after the Voice Automation beta is withdrawn. Requires a server API key with voice:manage.

### Usage

```bash
polymorfa voice credential delete CREDENTIAL [flags]
```

### Arguments

- `CREDENTIAL` (required). Provider credential ID.

### Flags

- `--yes` (boolean). Confirm permanent deletion without prompting.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

## polymorfa voice credential list

List provider credentials (beta).

List the team-wide provider credentials and, with --project, that project's own. Keys are never returned; each credential shows its fingerprint and status. Requires a server API key with voice:read. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice credential list [flags]
```

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa voice credential list
```

```bash
polymorfa voice credential list --project 018f0000-0000-7000-8000-000000000002
```

## polymorfa voice credential verify

Check a provider credential again (beta).

Check the stored key with the provider again and show the updated status. A rejected key fails with provider_credential_invalid (exit code 2); an unreachable provider with provider_unavailable (exit code 5). Requires a server API key with voice:manage. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice credential verify CREDENTIAL [flags]
```

### Arguments

- `CREDENTIAL` (required). Provider credential ID.

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

## polymorfa voice credential view

Show a provider credential (beta).

Show one provider credential: its provider, label, key fingerprint, status and last error. The key is never returned. Requires a server API key with voice:read. Voice Automation is a beta (calls.voice-automation) for enrolled teams only; other teams get voice_not_enabled (exit code 6).

### Usage

```bash
polymorfa voice credential view CREDENTIAL [flags]
```

### Arguments

- `CREDENTIAL` (required). Provider credential ID.

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).
