Voices

Choose the voice for a synthesis with voice_id. Two kinds of voices are available:

Your voices - voices you cloned, plus voices you "added" from the Voice Square.
Public voices - voices shared publicly on the Voice Square. Use their id directly; you don't need to add them and they don't use a voice slot.

The voice object

{
  "id": "2d7c8f0e-5a1b-4c3e-9f7a-1b2c3d4e5f60",
  "object": "voice",
  "name": "Warm Narrator",
  "description": "Great for audiobook narration",
  "status": "ready",
  "language": "en",
  "gender": "female",
  "age_group": "youth",
  "tags": ["scenario.audiobook"],
  "avatar_url": "https://…",
  "preview_audio_url": "https://…",
  "is_public": false,
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-01T08:00:00.000Z"
}

Field	Description
`status`	`ready` can be used; `pending` is processing; `failed` means cloning failed
`language`	Main language of the voice, may be `null`
`gender` / `age_group`	Gender and age group, `null` when not set
`preview_audio_url`	Sample audio, may be `null`
`is_public`	`true` for public (read-only) voices, which also include `usage_count` but not `tags`, `created_at`, or `updated_at`

List your voices

GET /api/v1/voices?page=1&limit=20&search=narrator

Parameter	Description
`page`	Page number, starting at 1
`limit`	Items per page, 1–100, default 20
`search`	Search by name

Response:

{
  "code": 0,
  "message": "ok",
  "data": { "object": "list", "items": [ /* voice objects */ ], "page": 1, "limit": 20, "total": 3, "has_more": false }
}

List public voices

GET /api/v1/voices/public?page=1&limit=20&search=news

Sorted by popularity. limit is at most 50. There is no total - use has_more to see whether another page exists.

Get a voice

GET /api/v1/voices/{id}

Works for your own voices and public voices. Returns 404 NOT_FOUND if the voice doesn't exist or you can't access it.

Clone a voice

Upload a recording to create your own voice. The request is multipart/form-data.

curl https://voiceailabs.com/api/v1/voices \
  -H "Authorization: Bearer $VAL_API_KEY" \
  -H "Idempotency-Key: clone-host-anna" \
  -F "name=Host Anna" \
  -F "language=en" \
  -F "consent=true" \
  -F "[email protected]"

Parameter	Required	Description
`audio`	Yes	Recording: WAV, MP3, OGG, WEBM or M4A; 3 seconds – 5 minutes, 10–30 seconds recommended; within your plan's size limit
`name`	Yes	Voice name, up to 100 characters
`consent`	Yes	Must be `true` - confirms you own this voice or have the owner's permission
`description`	No	Up to 500 characters
`language`	No	`zh`, `en`, `yue`, `ja`, `ja-asmr`, `ko`, `fr`, `es`, `pt`, `de`; detected automatically by default
`gender`	No	`female`, `male`, `neutral`
`age_group`	No	`child`, `teen`, `youth`, `middle_aged`, `senior`

Returns 201 with the voice object - usually already ready.

Consent

Only clone your own voice or a voice you have explicit permission to use. Impersonation, fraud and misleading content are prohibited.

Recording tips: one speaker, a quiet room, no background music, moderate volume without clipping. If the sample fails the quality check you get SAMPLE_QUALITY_FAILED with the problems listed in data.issues:

{
  "code": -1,
  "message": "The audio sample did not pass the quality check",
  "data": {
    "error_code": "SAMPLE_QUALITY_FAILED",
    "retryable": false,
    "request_id": "…",
    "issues": [{ "code": "too_short", "severity": "error" }]
  }
}

Possible errors: CONSENT_REQUIRED, VOICE_LIMIT_REACHED (no voice slots left), UNSUPPORTED_AUDIO_FORMAT, UPGRADE_REQUIRED (file exceeds your plan's size limit), FILE_TOO_LARGE (over 30MB), SAMPLE_QUALITY_FAILED, INVALID_REQUEST (invalid parameters, such as a language, gender, or age_group outside the allowed values), SYSTEM_BUSY (cloning timed out; retry later).

Delete a voice

DELETE /api/v1/voices/{id}

You can only delete your own voices. Deleting frees a voice slot and cannot be undone. Audio you already generated is not affected.

{ "code": 0, "message": "ok", "data": { "id": "2d7c…", "object": "voice", "deleted": true } }