# List voices API

Canonical docs: https://platform.sonilo.com/docs/api/dubbing-voices
Source path: /es/docs/api/dubbing-voices
Runtime API host: https://api.sonilo.com/v1

Do not send API requests to platform.sonilo.com, docs.sonilo.com, or local docs URLs. Documentation pages are for reading only. Send runtime requests to https://api.sonilo.com/v1 with Authorization: Bearer sk_your_api_key.

## Endpoint

GET /v1/dubbing/voices

## Summary

List the voices a video translation request can use as voice, or as values in voices, instead of a voice modeled on the original speaker.

## Use This For

- Choosing a voice per speaker before calling POST /v1/dubbing with voices and speakers.
- Showing voice options filtered by target language.

## Request

- `language` (string; optional; query parameter): Only the voices that speak this language code.
- `gender` (string; optional; query parameter; one of `female`, `male`): Optional. `female` or `male`.
- `age` (string; optional; query parameter; one of `child`, `teen`, `adult`, `senior`): Optional. `child`, `teen`, `adult` or `senior`. Any other value for a filter returns `422`.
- `style` (string; optional; query parameter): One style tag or several comma-separated; returns only voices that have all of them.

Machine-readable schema: https://platform.sonilo.com/openapi.json

### Usage notes

- style: optional query parameter, one style tag or several comma-separated (e.g. deep,calm); returns only voices that have all of them. Tags: low-pitch, mid-pitch, high-pitch, warm, bright, deep, soft, clear, husky, smooth, crisp, calm, lively, playful, authoritative, gentle. Filters combine; any other value is 422.

## Response And Errors

- 200 returns voices, each with voice_id, name, gender (female or male), age (child, teen, adult or senior), style, tags (one pitch tag, then tone and energy), languages (the codes it speaks), preview_url (the English audio sample, or null) and previews (a short audio sample per language: language code to URL). Sample links expire after 24 hours.
- 401 auth_invalid and 422 unprocessable_entity should be handled explicitly.

## Example

```bash
curl "https://api.sonilo.com/v1/dubbing/voices?language=pt&gender=male&age=senior" \
  -H "Authorization: Bearer sk_your_api_key"
```

## Shared Error Handling

- 401 auth_invalid: set Authorization: Bearer sk_your_api_key on the request.
- 402 payment_required or insufficient_balance: add credits before rerunning; do not create fake audio.
- 403 forbidden: the key is valid but the account or service permission is missing.
- 404 not_found: check the endpoint path and host. Use https://api.sonilo.com/v1, not a docs URL.
- 429 rate_limit_exceeded: honor Retry-After and retry with backoff.

## Endpoint Vocabulary

- GET /v1/account/services
- GET /v1/account/usage
- POST /v1/text-to-music
- POST /v1/video-to-music
- POST /v1/video-to-video-music
- POST /v1/audio-ducking
- POST /v1/text-to-sfx
- POST /v1/video-to-sfx
- POST /v1/video-to-video-sfx
- POST /v1/video-to-sound
- POST /v1/video-to-video-sound
- GET /v1/tasks/{task_id}